Elastic Path Production Tools

Catalog Syndication API

Catalog Syndication API

Content Management Systems (CMS) can retrieve Elastic Path Commerce Manager catalog updates through Syndication API, a REST Level 2 web service.

Elastic Path Syndication API deploys in Elastic Path integration Server. For the CMS who consume Syndication API, Elastic Path Commerce Manager administrators must create a role as a Web service access user. A web service access user is a user who can connect an external application to Elastic Path Commerce through the application. For more information about the roles, see the Role-Based Security in the Commerce Manager section.

Syndication API can fetch category projections for the following entities:

  • Attributes
  • Offers
  • Options
  • Brands
  • Field metadata
  • Categories

You need the URI, store code, type, and code to fetch category projections. Each of the following parameters in the URI represents an API request:

Parameter Description
store_code The code of the store, such as, Mobee.
type The type of entity, such as, brand, or offer.
code The code of the entity, such as, colour, or size.
The following is an example syndication URI:
http://<host>:<port>/integration/api/syndication/v1/catalog/<store_code>/<type>/<code>
The following paths are available for Syndication API:
Path Description
/catalog/{storeCode}/optionevents Sends an event message to get options.
/catalog/{storeCode}/options Reads the recent version of all options available within a store. Returns all results with pagination.
/catalog/{storeCode}/options/{optionCode} Reads the recent version of a specific option.
/catalog/{storeCode}/offerevents Sends an event message to get offers.
/catalog/{storeCode}/offers Reads the recent version of all offers available within a store. Returns all results with pagination.
/catalog/{storeCode}/offers/{attributeCode} Reads the recent version of a specific offer.
/catalog/{storeCode}/brandevents Sends an event message to get brands.
/catalog/{storeCode}/brands Reads the recent version of all brands available within a store. Returns all results with pagination.
/catalog/{storeCode}/brands/{brandCode} Reads the recent version of a specific brand.
/catalog/{storeCode}/attributeevents Sends an event message to get attributes.
/catalog/{storeCode}/attributes Reads the recent version of all attributes available within a store. Returns all results with pagination.
/catalog/{storeCode}/attributes/{attributeCode} Reads the recent version of a specific attribute.
/catalog/{storeCode}/fieldmetadataevents Sends an event message to get field metadata.
/catalog/{storeCode}/fieldmetadata Reads the recent version of all field metadata available within a store. Returns all results with pagination.
/catalog/{storeCode}/fieldmetadata/{fieldMetadataCode} Reads the recent version of all field metadata.

You can also get specific or multiple projections in a single request with the following additional parameters:

Parameter Description Type Default Value
limit Specify the amount of return results in a single request. Integer 10
startAfter Return results next in pagination. The parameter starts on the last item from the previous request. String Returns the first number after the specified limit.
modifiedSince Return any updates from a specific timestamp. Timestamp Returns all options if the parameter is omitted.
modifiedSinceOffset Calculates additional time in minutes prior to the modifiedSince parameter to compensate for long running transactions. integer 30 if parameter is omitted.

Request and Response Messages

The catalog projection request message includes the information to get event type, GUID, and more. The following example shows an event message for the updates to options for a store:

{
    "eventType": {
        "@class": "CatalogEventType",
        "name": "OPTIONS_UPDATED"
    },
    "guid": "AGGREGATE",
    "data": {
        "type": "option",
        "store": "MyStore",
        "modifiedDateTime": "2018-01-01T14:47:00+00:00",
        "codes": [
            "COLOUR",
            "SHAPE"
        ]
    }
}

The catalog projection response message includes information about the projections, such as, type, translations, and more. The following example shows a projection for option type:

"results": [
    {
        identity: {
            type: option
            code: COLOUR
            store: ca
        }
        modifiedDateTime: 2018-01-01T14:47:00+00:00
        deleted: false
        translations: [
            {
                language: en
                displayName: Colour
                optionValues: [
                    {
                        value: RED
                        displayValue: Red
                    }
                    {
                        value: BLUE
                        displayValue: Blue
                    }
                ]
            }
            {
                language: fr
                displayName: Couleur
                optionValues: [
                    {
                        value: RED
                        displayValue: Rouge
                    }
                    {
                        value: BLUE
                        displayValue: Bleu
                    }
                ]
            }
        ]
    },
    {
        identity: {
            type: option
            code: SHAPE
            store: ca
        }
        modifiedDateTime: 2018-01-01T14:47:00+00:00
        deleted: true
    }
]

Tombstone Projections

A tombstone projection is when a projection no longer contains any content. The purpose of the tombstone projection is to review historical data or for auditing purposes. The deleted flag state is set to "true" in the projection.