Built-in Commerce Connector REST API
Introduction
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/ |
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=bloomreach |
|
_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=bloomreach), 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=bloomreach), 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=bloomreach), 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=bloomreach), 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"
}
]
}
}
.