Using the Catalog API

This API requires Authentication.

Create a catalog

POST /catalogs

Query Parameters

Name	Type	Description
tenant*	string
environment*	string

Headers

Name	Type	Description
Authorization*	string	Bearer token containing the following permission:

Request Body

Name	Type	Description
catalog*	object	catalog

200 catalog successfully created, return the catalog version.

{{catalog.version}}

400: Bad Request Code 3 : Tenant and Environment are required

{
    // Response
}

400: Bad Request The limit of 2 catalogs is reached

{
    // Response
}

400: Bad Request Catalog validation failed

{
    // Response
}

409: Conflict Error during the catalog creation on FHR

{
    // Response
}

Remember! Catalog API can handle only 2 catalogs at the same time. If this limit is reached, one inactive catalog must be deleted by using the API before creating a new one. Determining the inactive catalog is done by listing all catalogs API.

Create a catalog returns the created catalog version. The catalog state is managed by the API. New catalogs are always set as Inactive and you must use the "Activate" method to this activate it.

The catalogCategoryTrees nested JSON object is optional.

Example of a catalog creation body:

{
    "catalogItemSchemas": [
        {
            "name": "product",
            "version": 1
        }
    ],
    "catalogCategoryTrees": [
       {
           "name": "root_name",
           "version": 2
       }
    ]
}

Multiple category trees

In the standard usecase the catalog will contain one single category tree. However, based on the data model used the category tree might grow and get harder to manage. We consider category trees larger than 4 MB too large, and we recommend splitting the tree if this limit is approached.

One single category tree cannot exceed 4 MB in size. Use multiple trees if that is the case.

Example of catalog creation with multiple category trees

{
    "catalogItemSchemas": [
        {
            "name": "product",
            "version": 1
        }
    ],
    "catalogCategoryTrees": [
        {
            "name": "categoryTreeDividedPart1",
            "version": 2
        },
        {
            "name": "categoryTreeDividedPart2",
            "version": 1
        }
    ]
}

Delete a catalog

DELETE https://items.attraqt.io/catalogs/{version}

Path Parameters

Name	Type	Description
version*	integer	​Version of catalog to delete.

Query Parameters

Name	Type	Description
tenant*	string
environment*	string

Headers

Name	Type	Description
Authorization*	string	Bearer token containing the following permission:

200

404: Not Found The requested catalog is not found

{
    // Response
}

400: Bad Request The catalog must be inactive to be deleted

{
    // Response
}

Only Inactive catalogs can be deleted.

Attention: removing a catalog will delete items attached to this catalog, this operation can't be undone

Activate a catalog version

POST https://items.attraqt.io/catalogs/activate/{version}

Path Parameters

Name	Type	Description
version*	integer	​Version of catalog to activate.

Query Parameters

Name	Type	Description
tenant*	string
environment*	string
minItemCount	integer	The minimum number of items expected in this catalog activation. If the item processing pipeline detects less items than this number, then the catalog activation will fail. The feedback message in the corresponding Feedback API will indicate both this number and the detected number.

Headers

Name	Type	Description
Authorization*	string	Bearer token containing the following permission:

200

400: Bad Request Tenant and Environment are required

{
    // Response
}

400: Bad Request Catalog already active or a catalog is already in activation

{
    // Response
}

404: Not Found Catalog Not found

{
    // Response
}

409: Conflict Error delivering metadata to FHR or during the catalog activation on FHR

{
    // Response
}

Get active catalogue version

GET https://items.attraqt.io/catalogs/active

Get the catalog version currently promoted

Query Parameters

Name	Type	Description
tenant*	string
environment*	string

Headers

Name	Type	Description
Authorization*	string	Bearer token containing the following permission:

200

{{catalog}}

404: Not Found

{
    // Response
}

List catalogs

GET https://items.attraqt.io/catalogs

Query Parameters

Name	Type	Description
tenant*	string
environment*	string

Headers

Name	Type	Description
Authorization*	string	Bearer token containing the following permission:

200

Api errors

Error category	Description
CATALOG_TENANT_ENV	Tenant and Environment are required
CATALOG_SCHEMAS	Error in given Item Schema
CATALOG_CATEGORY_TREES	Error in given Category tree
CATALOG_LIMIT_REACHED	The limit of 2 catalogs is reached
CATALOG_ALREADY_ACTIVE	The catalog is already active or in activation state
CATALOG_FHR_FAILED	Error in FHR api
CATALOG_NOT_ACTIVE	The catalog must be in activating state to perform the action
CATALOG_DELETION_ACTIVE	The catalog must be inactive to be deleted