Catalog Syndication API

External systems 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. 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, 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.

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.