Catalog Tutorials

How to localize your catalog

The name and the description attribute of a catalog support localization. This means that you can provide values in multiple languages and also retrieve those values either localized, or all together, as you choose. Localization is controlled by the Content-Language and Accept-Language headers:

• Content-Language - this is used to specify which languages can be used in the request payload when creating or updating catalogs. The Content-Language request HTTP header defines language(s) that can be used in the payload. Request body may contain only translations that are matching the languages specified in the header. Possible values:

  • * - request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.

  • en, en,de, fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - request body may contain only translations for languages specified in the header (if they are available in tenant configuration).

• 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.

Note: When creating or updating catalogs, you must always provide localized fields (such as name and description) as maps of language codes to values, regardless of the Content-Language header value.

How to create a catalog and assign a category to it

You can assign categories to a catalog when creating or updating the catalog. The following procedure covers the latter scenario.

Create a catalog

Catalog names and descriptions are localized. When creating a new catalog, you must provide the catalog name and description as maps of language codes to values.

Looking for more info on localization? Check out Standard practices.

To create a new catalog, you need to send a request to the Creating a new catalog endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X POST 
  'https://api.emporix.io/catalog/{tenant}/catalogs' 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' 
  -H 'Content-Type: application/json' 
  -d '{
  "name": {
    "en": "Grocery catalog",
    "de": "Lebensmittelkatalog"
  },
  "description": {
    "en": "Catalog of grocery products.",
    "de": "Katalog von Lebensmittelprodukten."
  },
  "visibility": {
    "visible": false,
    "from": "2022-02-24T20:44:43.169Z",
    "to": "2023-07-24T20:44:43.169Z"
  },
  "publishedSites": [
    "Main"
  ],
  "categoryIds": [
    "3249485"
  ]
}

Create a category

For more information, check out How to create a category.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X POST 
  'https://api.emporix.io/category/{tenant}/categories?publish=true' 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' 
  -H 'Content-Language: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`' 
  -H 'Content-Type: application/json' 
  -H 'X-Version: v2' 
  -d '{
    "parentId": "056bcaf6-66b8-4ddd-9489-65c5f6449e74",
    "localizedName": {
      "en": "Floor Care",
      "de": "Bodenpflege"
    },
    "localizedDescription": {
      "en": "Floor Care",
      "de": "Bodenpflege"
    },
    "localizedSlug": {
      "en": "Floor-Care",
      "de": "Bodenpflege"
    },
    "ecn": [
      "AX6784",
      "123078",
      "SJUIOKM"
    ],
    "validity": {
      "from": "2022-01-05T12:44:51.871Z",
      "to": "2022-12-05T23:59:59.000Z"
    },
    "position": 5,
    "published": true,
    "mixins": {}
  }'

Assign the category to the catalog

To assign the newly created category to a catalog, you need to send a request to the Partially updating a catalog endpoint.

In the request body, insert the ID of the category into the categoryIds array. In this example, we also present how to set the visibility timeframe of the catalog with the visibility field.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X PATCH 
  'https://api.emporix.io/catalog/{tenant}/catalogs/{catalogId}' 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' 
  -H 'Content-Type: application/json' 
  -d '{
    "name": {
      "en": "This is the same catalog"
    },
    "description": {
      "en": "This catalog has been updated"
    },
    "visibility": {
      "visible": true,
      "from": "2022-02-24T20:44:43.169Z",
      "to": "2023-07-24T20:44:43.169Z"
    },
    "publishedSites": [
      "Main"
    ],
    "categoryIds": [
      "3249485"
    ],
    "metadata": {
      "version": 1
    }
  }'

The Catalog Service automatically checks for any category-deleted events. Every time a root category is deleted, it is automatically removed from all catalogs it belonged to.