Built-in Commerce Connector REST API - Bloomreach Experience - Open Source CMS

Built-in Commerce Connector REST API

This Bloomreach Experience Manager feature requires a standard or premium license. Please contact Bloomreach for more information.

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:

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.

If allowlist.props is not set or it is set to a blank string, then the apollo.server.url property will be allowded on its own by default.

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.
0 by default.

_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.
10 by default.

_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

The Cart REST service is for providing the cart data of the current visitor only, and it is meant to be exposed only in the content delivery tier (/site), not in content authoring (/cms).

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"
      }
   ]
}
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?