Catalog Management (1.0.0)

Download OpenAPI specification:Download

Emporix: documentation@emporix.com URL: https://emporix.com

The Catalog Management API gives you the tools required to structure your product offering the way it suites you best.
It provides the following capabilities and operations:

Structuring your products:

  • Create a new catalog
  • Modify an existing catalog
  • Remove a catalog you no longer need

List your catalogs:

  • Filtered, sorted and paged list of catalogs
  • List of catalogs holding a particular category
  • View catalog details

Localization

The name and the description attribute of a catalog support localization. This means that you can provide values in a specific locale and also retrieve those values either localized, or all together, as you choose.
Localization is controlled via two headers:

  • Accept-Language - this is used to specify how to retrieve catalogs. If a value is provided, then the resources will be returned in that locale. If '*' is provided as a value, or the header is missing, all locales saved on a resource will be returned for that resource.
  • Content-Language - this header is used to specify if the data that will be stored for this request has a particular locale or you are providing all the desired locales.

You can see detailed examples for the requests affected by this bellow.

List catalogs

Getting the filtered and sorted list of catalogs

Get the filtered list of catalogs for the specified tenant. Also, sorting and paging options are available. If none are given, default values will be used.

SecurityOAuth2
Request
path Parameters
tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2
query Parameters
name
string

Search by the name of the catalog. If you want to search for the name in a specific locale, you can just append the .<locale>, for example use name.de.

Example: name=name
description
string

Search by description of the catalog. If you want to search for the name in a specific locale, you can just append the .<locale>, for example use description.de.

Example: description=description
publishedSite
string

Search by a site name. The equal operator is used here, therefore the site name must match.

visibilityFrom
string <date>

Search by start date of the visibility of the catalog. It must follow the pattern yyyy-MM-dd.

Example: visibilityFrom=2022-01-28
visibilityTo
string <date>

Search by end date of the visibility of the catalog. It must follow the pattern yyyy-MM-dd.

Example: visibilityTo=2022-01-28
metadataUpdatedAt
string <date>

Search by last update date of the catalog. It must follow the pattern yyyy-MM-dd.

Example: metadataUpdatedAt=2022-01-28
pageNumber
integer <int32> >= 1
Default: 1

Page number to be retrieved. The number of the first page is 1. Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.

pageSize
integer <int32> >= 1
Default: 60

Number of catalogs to be retrieved per page.

sort
string

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. Sorting by name parameter works properly only if the Accept-Language header is set to a specific language or is empty with default language specified in the configuration service.

Example: sort=name,description:asc
header Parameters
X-Total-Count
boolean
Default: false

This flag specifies if the API client should receive a X-Total-Count header with the total number of elements that match the search filter.

Accept-Language
string
Default: *

List of properties used to sort the results, separated by commas. Possible values:

  • * - each internationalized field is returned as a map containing all available translations
  • en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
  • fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not available exception is thrown. This list must contains any possible extension for internationalized fields included in sort param.
Example: *, 'en', 'en,de,fr', 'en-EN', 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5'
Responses
200

The search was successful.

400

Request was syntactically incorrect. Details will be provided in the response payload.

500

An unexpected error prevented the server from fulfilling the request.

get/{tenant}/catalogs
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieving all catalogs for category
Get all catalogs with the specified category that belong to the tenant.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
categoryId
required
string
The unique id of the category, that will be matched with the category identifiers stored on catalogs.


 
 Example:  787323
query Parameters
pageNumber
integer <int32>   >= 1 
 Default:  1
Page number to be retrieved. The number of the first page is 1.
Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
pageSize
integer <int32>   >= 1 
 Default:  60
Number of catalogs to be retrieved per page.


 
sort
string
Fields to sort the response data by following order of the parameters from left to right.
Can contain multiple fields in format: field name:sort direction separated by a comma.
The colon with sort direction parameter is redundant and descending order is taken only
if it is equal to desc or DESC.
Ascending order is considered in any other case.
Sorting by name parameter works properly only if the Accept-Language header is set to
a specific language or is empty with default language specified in the configuration service.


 
 Example:  sort=name,description:asc
header Parameters
X-Total-Count
boolean
 Default:  false
This flag specifies if the API client should receive a X-Total-Count header with the total number of elements that match the search filter.


 
Accept-Language
string
 Default:  *
List of properties used to sort the results, separated by commas.
Possible values:


    

  • * - each internationalized field is returned as a map containing all available translations
    • 

  • en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
    • 

  • fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not available exception is thrown. This list must contains any possible extension for internationalized fields included in sort param.
    • 



 
 Example:  *, 'en', 'en,de,fr', 'en-EN', 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5'
Responses 
200
The search was successful.


400
Request was syntactically incorrect. Details will be provided in the response payload.


500
An unexpected error prevented the server from fulfilling the request.


get/{tenant}/catalogs/categories/{categoryId}
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieving a catalog by id
Get the catalog with the specified unique id that belongs to the tenant.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
catalogId
required
string
The unique id of the catalog.


 
 Example:  787323
Responses 
200
Catalog was successfully retrieved.


400
Request was syntactically incorrect. Details will be provided in the response payload.


404
Resource cannot be found


500
An unexpected error prevented the server from fulfilling the request.


get/{tenant}/catalogs/{catalogId}
Request samples 
Response samples 
application/json
{
  • "id": "3456454",
  • "name": {
    },
  • "description": {
    },
  • "status": "VISIBLE",
  • "visibility": {
    },
  • "publishedSites": [
    ],
  • "categoryIds": [
    ],
  • "metadata": {
    }
}
Catalog management
Creating a catalog
Creates a new catalog based on the provided request payload, for the specified tenant.




Required scopes


catalog.catalog_manage


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
Request Body schema: application/json
id
string  [ 1 .. 66 ] characters ^[a-zA-Z0-9_-]$
Custom catalog identifier. If not provided, it is automatically generated.


 
required
object or object
Name of the catalog must be a string if the Content-Language header is set or a map of translations if the header is missing.


 
object or object
Name of the catalog must be a string if the Content-Language header is set or a map of translations if the header is missing.


 
object (VisibilityInformation) 
Visibility configuration for a catalog


 
publishedSites
Array of strings
List of site identifiers on which the catalog is published.


 
categoryIds
Array of strings
List of root category identifiers that are assigned to the catalog.


 
Responses 
201
The catalog has been successfully created.


400
Request was syntactically incorrect. Details will be provided in the response payload.


403
Permission denied due to insufficient rights.


409
Given resource already exists.


500
An unexpected error prevented the server from fulfilling the request.


post/{tenant}/catalogs
Request samples 
application/json
{
  • "name": {
    },
  • "description": {
    },
  • "visibility": {
    },
  • "publishedSites": [
    ],
  • "categoryIds": [
    ]
}
Response samples 
application/json
{
  • "id": "4239475"
}
Upserting a catalog
Update or create the specified catalog.




Required scopes


catalog.catalog_manage


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
catalogId
required
string
The unique id of the catalog.


 
 Example:  787323
Request Body schema: application/json
required
object or object
Name of the catalog must be a string if the Content-Language header is set or a map of translations if the header is missing.


 
object or object
Name of the catalog must be a string if the Content-Language header is set or a map of translations if the header is missing.


 
object (VisibilityInformation) 
Visibility configuration for a catalog


 
publishedSites
Array of strings
List of site identifiers on which the catalog is published.


 
categoryIds
Array of strings
List of root category identifiers that are assigned to the catalog.


 
object (UpdateMetadata) 
 
Responses 
201
The catalog has been successfully created.


204
The catalog has been successfully updated.


400
Request was syntactically incorrect. Details will be provided in the response payload.


403
Permission denied due to insufficient rights.


404
Resource cannot be found


409
Resource conflict


500
An unexpected error prevented the server from fulfilling the request.


put/{tenant}/catalogs/{catalogId}
Request samples 
application/json
{
  • "name": {
    },
  • "description": {
    },
  • "visibility": {
    },
  • "publishedSites": [
    ],
  • "categoryIds": [
    ],
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "id": "4239475"
}
Removing catalog
Remove the specified catalog.




Required scopes


catalog.catalog_manage


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
catalogId
required
string
The unique id of the catalog.


 
 Example:  787323
Responses 
204
The catalog has been successfully removed.


400
Request was syntactically incorrect. Details will be provided in the response payload.


403
Permission denied due to insufficient rights.


404
Resource cannot be found


500
An unexpected error prevented the server from fulfilling the request.


delete/{tenant}/catalogs/{catalogId}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Unsupported locale format. Please provide one of: 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 or en-EN or en'"
}
Partially updating a catalog
Update the specified catalog, even partially.




Required scopes


catalog.catalog_manage


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
 Example:  saasdev2
catalogId
required
string
The unique id of the catalog.


 
 Example:  787323
Request Body schema: application/json
object or object
Name of the catalog must be a string if the Content-Language header is set or a map of translations if the header is missing.


 
object or object
Name of the catalog must be a string if the Content-Language header is set or a map of translations if the header is missing.


 
object (VisibilityInformation) 
Visibility configuration for a catalog


 
publishedSites
Array of strings
List of site identifiers on which the catalog is published.


 
categoryIds
Array of strings
List of root category identifiers that are assigned to the catalog.


 
required
object (Metadata) 
 
Responses 
204
The catalog has been successfully updated.


400
Request was syntactically incorrect. Details will be provided in the response payload.


403
Permission denied due to insufficient rights.


500
An unexpected error prevented the server from fulfilling the request.


patch/{tenant}/catalogs/{catalogId}
Request samples 
application/json
{
  • "name": {
    },
  • "description": {
    },
  • "visibility": {
    },
  • "publishedSites": [
    ],
  • "categoryIds": [
    ],
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "property1": "string",
  • "property2": "string"
}