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