Built-in Commerce Connector REST API
Introduction
Goal
Use the built-in Commerce Connector REST API to retrieve data from the Commerce Backend Platforms in your application.
Background
The built-in Commerce Connector REST API provides JSON APIs to retrieve data from the Commerce Backend Platforms through Commerce Connector Modules. The responses represent the models of Commerce Connector SDK equivalently in JSON.
REST API Endpoints
The Commerce Connector REST API is available in both content delivery applications (e.g, "/site") and content authoring applications (e.g, "/cms"), with the following endpoints by default:
|
Application Type |
Endpoint |
Description |
Example URLs |
|
Delivery (e.g, "/site") |
/restservices/* |
Deployed as HST-2 Plain JAX-RS Services. It is possible to customize the mount path through HST-2 configurations |
/site/restservices/categories/, /site/restservices/products/ |
| Authoring (e.g, "/cms") |
/ws/starterstore/* |
Deployed as Repository JAX-RS Service. |
/cms/ws/starterstore/categories/, /cms/ws/starterstore/products/ |
REST API for Commerce Connector Properties
Since v14.3, there is one special REST API which allows reading some selected properties of a specified Commerce Connector. One of the typical use cases is when an SPA needs to communicate with the brX GraphQL Service for commerce data, it can find out the URL of the brX GraphQL Service from the properties of the Commerce Connector. For details on this use case, see Commerce Connector Configuration for brX GraphQL Service.
Each Commerce Connector can be configured in the Properties field with extra properties in the Commerce Connector document. To read some selected properties, make a GET request on either one of the following endpoints:
- /ws/starterstore/connectors/{connectorId}/props
(e.g, http://localhost:8080/cms/ws/starterstore/connectors/commercetools/props) - /restservices/connectors/{connectorId}/props
(e.g, http://localhost:8080/site/restservices/connectors/commercetools/props)
The response will be like below:
{
"apollo.server.url": "https://api.example.com/graphql"
}
Note that each available property of a Commerce Connector will be included as a property in the JSON object response. For example, if you make one more property available (e.g, "another.api.url"), then the property will be serialized next to the "apollo.server.url" property in the above example.
List of Allowed Exposable Commerce Connector Properties
For security reasons, it is not desirable to expose all properties of the Commerce Connector. Therefore, the REST API does not expose all properties by default. Instead, it reads a special property named "allowlist.props" to allow the specific properties to be serialized. The "allowlist.props" property specifies a single or multiple property names to be serialized in a comma separated string.
Suppose you have configured the following properties in a Commerce Connector document:
|
Property Name |
Property Value |
|
scope |
"my_merchant_home" |
|
role |
"my_merchant_role" |
|
allowlist.props |
apollo.server.url, another.api.url |
|
apollo.server.url |
https://api.example.com/graphql |
| another.api.url | https://api.example.com/v1 |
In this case, the client will get a response like the following:
{
"apollo.server.url": "https://api.example.com/graphql",
"another.api.url": "https://api.example.com/v1"
}
The other properties such as scope or role in this example will not be included in the response as they are not in the allowlist.props property.
Common Query Parameters
The following common query parameters are provided by default:
|
Name |
Required |
Description |
Examples |
|
_connector |
No |
The identifier of the Commerce Connector from which you want to retrieve data. If not specified, it uses the identifier of the Default Commerce Connector in the channel configuration by default. |
_connector=brsm |
|
_offset |
No |
Offset of the iterating query result. Applicable only in search APIs. |
_offset=10 |
|
_limit |
No |
Limit of the iterating query result. Applicable only in search APIs. Note responses can differ based on the specific backend used. |
_limit=10 |
|
q |
No |
Full text search query term used in the query execution. Applicable only in search APIs. |
q=lorem+ipsum |
Category REST API
Category Search
To search categories, make a GET request on /restservices/categories (e.g, http://localhost:8080/site/restservices/categories?_connector=brsm), which responds with data like the following example:
{
"offset":0,
"limit":-1,
"totalSize":42,
"facetResult":null,
"suggestedActions":{
"actions":[
]
},
"size":30,
"collection":[
{
"id":"VPA_VA_MCLASS",
"displayName":"M-Class",
"children":[
{
"id":"VPA_VEHICLE_ADDONS",
"displayName":"Addons",
"children":[
]
}
]
},
//...
{
"id":"VPA_T_MICHELIN",
"displayName":"Michelin",
"children":[
{
"id":"VPA_TIRES",
"displayName":"Tires",
"children":[
]
}
]
},
//...
{
"id":"VESTRI_APPAREL_MENS",
"displayName":"Womens",
"children":[
{
"id":"VESTRI_BM_APPAREL",
"displayName":"Apparel",
"children":[
]
}
]
},
//...
]
}
You can specify any of Common Query Parameters to narrow the search result.
Category Detail
To find a category item with categoryId, make a GET request on /restservices/categories/{categoryId} (e.g, http://localhost:8080/site/restservices/categories/VPA_VA_MCLASS?_connector=brsm), which responds with data like the following example:
{
"id":"VPA_VA_MCLASS",
"displayName":"M-Class",
"children":[
{
"id":"VPA_VEHICLE_ADDONS",
"displayName":"Addons",
"children":[
]
}
]
}
Note that category models are hierarchically organized so child categories are included in the parent category in "children" property.
Product REST API
Product Search
To search products, make a GET request on /restservices/products (e.g, http://localhost:8080/site/restservices/products?_connector=brsm), which responds with data like the following example:
{
"offset":0,
"limit":10,
"totalSize":66,
"facetResult":{
"facetFields":[
{
"name":"category",
"values":[
{
"id":"VPA_VA_MCLASS",
"parentId":"",
"name":"M-Class",
"count":9
},
{
"id":"VPA_VEHICLE_ADDONS",
"parentId":"",
"name":"Vehicle Addons",
"count":8
},
//...
{
"id":"VSTRI_BM_APPAREL",
"parentId":"",
"name":"Apparel",
"count":1
}
]
},
{
"name":"sizes",
"values":[
{
"id":"large",
"parentId":null,
"name":"large",
"count":22
},
{
"id":"medium",
"parentId":null,
"name":"medium",
"count":22
},
{
"id":"small",
"parentId":null,
"name":"small",
"count":21
},
{
"id":"xlarge",
"parentId":null,
"name":"xlarge",
"count":14
},
//...
]
},
{
"name":"brand",
"values":[
]
},
{
"name":"colors",
"values":[
{
"id":"red",
"parentId":null,
"name":"red",
"count":15
},
{
"id":"black",
"parentId":null,
"name":"black",
"count":16
},
//...
{
"id":"silver",
"parentId":null,
"name":"silver",
"count":1
}
]
},
//...
]
},
"suggestedActions":{
"actions":[
]
},
"size":10,
"collection":[
{
"itemId":{
"id":"M-Class-C",
"code":"10001"
},
"displayName":"M-Class Sports Coupe",
"description":"The M-Class Coupe joyful driving demeanor, powerful motors, and stunning styling make it one of the favorite sports cars, as evidenced by its regular appearance on the roads. M-Class Coupe is a focused performance machine, as our electric sports car, its seriousness sets the stage for the rest of the lineup. Enjoy the freedom this can give you.",
"imageSet":{
"original":{
"dimension":null,
"links":{
"self":{
"href":"https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10001.png",
"ref":null
}
}
},
"thumbnail":{
"dimension":null,
"links":{
"self":{
"href":"https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10001.png",
"ref":null
}
}
}
},
"listPrice":{
"moneyAmounts":[
{
"amount":47999.0,
"currency":null,
"displayValue":"47999.0"
}
]
},
"purchasePrice":{
"moneyAmounts":[
{
"amount":47999.0,
"currency":null,
"displayValue":"47999.0"
}
]
}
},
{
"itemId":{
"id":"T50-PU",
"code":"10003"
},
"displayName":"T50 SD Pickup Truck",
"description":"The Vestri T50 Pickup Truck gives you the tool you need to get the job done. Using an electric/hybrid option you can disappear into remote areas still only supporting the older internal combustion engines. But then switch back to electric power when utility service is available.",
"imageSet":{
"original":{
"dimension":null,
"links":{
"self":{
"href":"https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10003.png",
"ref":null
}
}
},
"thumbnail":{
"dimension":null,
"links":{
"self":{
"href":"https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10003.png",
"ref":null
}
}
}
},
"listPrice":{
"moneyAmounts":[
{
"amount":44500.0,
"currency":null,
"displayValue":"44500.0"
}
]
},
"purchasePrice":{
"moneyAmounts":[
{
"amount":44500.0,
"currency":null,
"displayValue":"44500.0"
}
]
}
},
//...
{
"itemId":{
"id":"HOOD_PANELS",
"code":"38186"
},
"displayName":"Hood Panels",
"description":"Hoods are usually casualties in a front end collision, but they can also suffer damage at the leading edge from airborne road debris, and on the surface from falling objects like hail or tree limbs. Since a typical hood is mostly flat and occupies such a prominent position, any damage stands out and will detract from the vehicle's appearance. A new hood from the dealer is very expensive, but don't let that deter you from making the repair. more details on - https://www.carid.com/replace/hood-panel.html",
"imageSet":{
"original":{
"dimension":null,
"links":{
"self":{
"href":"https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/38186.png",
"ref":null
}
}
},
"thumbnail":{
"dimension":null,
"links":{
"self":{
"href":"https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/38186.png",
"ref":null
}
}
}
},
"listPrice":{
"moneyAmounts":[
{
"amount":589.0,
"currency":null,
"displayValue":"589.0"
}
]
},
"purchasePrice":{
"moneyAmounts":[
{
"amount":589.0,
"currency":null,
"displayValue":"589.0"
}
]
}
}
]
}
You can specify any of Common Query Parameters to narrow the search result.
Product Detail
To find a product item with itemId (e.g, { "id":"M-Class-C", "code":"10001" }), make a GET request on /restservices/products/{itemIdValue} (e.g, http://localhost:8080/site/restservices/products/M-Class-C___10001/?_connector=brsm), which responds with data like the following example. Note that the path parameter, {itemIdValue}, should concatenate "id" and "code" of the itemId with the delimiter, "___" (three underscores).
{
"itemId":{
"id":"M-Class-C",
"code":"10001"
},
"displayName":"M-Class Sports Coupe",
"description":"The M-Class Coupe joyful driving demeanor, powerful motors, and stunning styling make it one of the favorite sports cars, as evidenced by its regular appearance on the roads. M-Class Coupe is a focused performance machine, as our electric sports car, its seriousness sets the stage for the rest of the lineup. Enjoy the freedom this can give you.",
"imageSet":{
"original":{
"dimension":null,
"links":{
"self":{
"href":"https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10001.png",
"ref":null
}
}
},
"thumbnail":{
"dimension":null,
"links":{
"self":{
"href":"https://s3-us-west-2.amazonaws.com/elasticpath-demo-images/VESTRI_VIRTUAL/10001.png",
"ref":null
}
}
}
},
"listPrice":{
"moneyAmounts":[
{
"amount":47999.0,
"currency":null,
"displayValue":"47999.0"
}
]
},
"purchasePrice":{
"moneyAmounts":[
{
"amount":47999.0,
"currency":null,
"displayValue":"47999.0"
}
]
}
}
Cart REST API
Cart Data
To retrieve the cart data for the current visitor, make a GET request on /restservices/cart/ (e.g, http://localhost:8080/site/restservices/cart/).
If a cart exists, you will get a 200 response with data like the following example:
{
"id":"a25105dc-6301-4a4c-983e-f1a255b89a38",
"totalQuantity":2,
"revision":7,
"orderId":null,
"entries":[
{
"id":"var1-5a64dbea-fed5-422c-9267-42224e9fb2a8",
"quantity":2,
"items":[
{
"itemId":{
"id":"var1-5a64dbea-fed5-422c-9267-42224e9fb2a8",
"code":"LeCreuset_SauteusePan"
},
"displayName":"Le Creuset Signature Sauteuse Pan",
"description":"",
"imageSet":{
"original":{
"dimension":null,
"links":{
"self":{
"href":"https://acc545be1d5fd66d9268-e6ee5bd70ad552747c060c238eaa7bc8.ssl.cf3.rackcdn.com/Le-Creuset-Signature-kTLphxPW.jpg",
"ref":null
}
}
},
"thumbnail":{
"dimension":null,
"links":{
"self":{
"href":"https://acc545be1d5fd66d9268-e6ee5bd70ad552747c060c238eaa7bc8.ssl.cf3.rackcdn.com/Le-Creuset-Signature-kTLphxPW-thumb.jpg",
"ref":null
}
}
}
},
"listPrice":{
"moneyAmounts":[
{
"amount":479.0,
"currency":"USD",
"displayValue":"USD 479.0"
}
]
},
"purchasePrice":{
"moneyAmounts":[
{
"amount":479.0,
"currency":"USD",
"displayValue":"USD 479.0"
}
]
},
"attributes":{
"custom-attribute":"Dune"
}
}
]
},
{
"id":"var1-074e7c30-fb98-4cd8-ac96-07207f840d1f",
"quantity":1,
"items":[
{
"itemId":{
"id":"var1-074e7c30-fb98-4cd8-ac96-07207f840d1f",
"code":"LeCreuset_Saucepan"
},
"displayName":"Le Creuset Signature Saucepan 16cm",
"description":"",
"imageSet":{
"original":{
"dimension":null,
"links":{
"self":{
"href":"https://acc545be1d5fd66d9268-e6ee5bd70ad552747c060c238eaa7bc8.ssl.cf3.rackcdn.com/Le-Creuset-Signature-PhVCYq4n.jpg",
"ref":null
}
}
},
"thumbnail":null
},
"listPrice":{
"moneyAmounts":[
{
"amount":349.0,
"currency":"USD",
"displayValue":"USD 349.0"
}
]
},
"purchasePrice":{
"moneyAmounts":[
{
"amount":349.0,
"currency":"USD",
"displayValue":"USD 349.0"
}
]
},
"attributes":{
}
}
]
}
]
}
If no cart exists (yet), you will get a 404 response like the following:
{
"errors":[
{
"message":"Cart not found.",
"path":null,
"code":"404"
}
]
}
If the backend connector doesn't allow anonymous carts you will get a 401 response like the following:
{
"errors":[
{
"message":"Expecting a visitor context",
"path":null,
"code":"401"
}
]
}