Skip to main content
Version: 8.2.x

Catalog Syndication API

External systems can retrieve Self-Managed Commerce Manager catalog updates through Syndication API, a REST Level 2 web service. Elastic Path Syndication API deploys in Elastic Path Integration Server. Each HTTP request that is made to Catalog Syndication API must have an Authorization header with the value Basic <token> with a Base64 encoded string of <username>:<password>. For example, for a user with the username of login and a password of 123456, the request must have an Authorization header with the value Basic bG9naW46MTIzNDU2. If you decode bG9naW46MTIzNDU2 using Base64 decoder, this would result into the string login:123456.

For the external systems that consume Syndication API, Self-Managed 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 Self-Managed Commerce through the application. For more information about the roles, see the Role-Based Security in the Commerce Manager section.

Category Projection Entities​

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:

store_code​

The code of the store, such as Mobee.

type​

The type of entity:

  • Offer
  • Category
  • Attribute
  • Brand
  • Option
  • FieldMetadata

code​

The code of the entity.

The following is an example syndication URI:

http://<host>:<port>/integration/api/syndication/v1/catalog/<store_code>/<type>/<code>

Syndication API​

The following paths are available for Syndication API:

/catalog/{store_code}/optionevents​

Sends an event message to get related options.

/catalog/{store_code}/options​

Reads the recent version of all options available within a store. Returns all results with pagination.

/catalog/{store_code}/options/{optionCode}​

Reads the recent version of a specific option.

/catalog/{store_code}/offerevents​

Sends an event message to get related offers.

/catalog/{store_code}/offers​

Reads the recent version of all offers available within a store. Returns all results with pagination.

/catalog/{store_code}/offers/{attributeCode}​

Reads the recent version of a specific offer.

/catalog/{store_code}/brandevents​

Sends an event message to get related brands.

/catalog/{store_code}/brands​

Reads the recent version of all brands available within a store. Returns all results with pagination.

/catalog/{store_code}/brands/{brandCode}​

Reads the recent version of a specific brand.

/catalog/{store_code}/attributeevents​

Sends an event message to get related attributes.

/catalog/{store_code}/attributes​

Reads the recent version of all attributes available within a store. Returns all results with pagination.

/catalog/{store_code}/attributes/{attributeCode}​

Reads the recent version of a specific attribute.

/catalog/{store_code}/fieldmetadataevents​

Sends an event message to get related field metadata.

/catalog/{store_code}/fieldmetadata​

Reads the recent version of all field metadata available within a store. Returns all results with pagination.

/catalog/{store_code}/fieldmetadata/{fieldMetadataCode}​

Reads the recent version of all field metadata.

Additional API Parameters​

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

limit​

Type: Integer

Default Value: 10 Specify the amount of return results in a single request.

startAfter​

Type: String

Default Value: Returns the first number after the specified limit.

Return results next in pagination. The parameter starts on the last item from the previous request.

modifiedSince​

Type: Timestamp

Default Value: Returns all options if the parameter is omitted.

Return any updates from a specific timestamp.

modifiedSinceOffset​

Type: integer

Default Value: 30 if parameter is omitted.

Calculates additional time in minutes prior to the modifiedSince parameter to compensate for long running transactions.

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.

Last updated on