Delivery API Support
Info: This feature in Bloomreach Content requires a standard or premium license. Contact Bloomreach for details.
Overview
Bloomreach Commerce Accelerator includes built-in support for Single Page Applications (SPA). By default, it exposes Commerce Model objects through the Delivery API. SPA applications can retrieve these objects—such as CategoryModel and ItemLike (ItemModel or ItemVariant)—in JSON format and use them to render UI components.
The Delivery API serializes Commerce Model objects to JSON following standard Java Bean property conventions. For example, the CategoryModel#getId() method maps to the "id" property in JSON, and CategoryModel#getDisplayName() maps to "displayName". For details on the design of Commerce Model objects, see Introduction to Commerce Connector SDK.
Example Delivery API Responses
Category-Related HST Components
When a page includes category-related HST Components, such as "Category Highlight," the component automatically contributes the relevant CategoryModel to the Delivery API. The following example shows a typical API response:
{ "id":"r39", "_links":{ "self":{ "href":"http://localhost:8080/site/fr/resourceapi/categories/_default_" }, "site":{ "href":"http://localhost:8080/site/fr/categories/_default_" } }, "page":{ "id":"r39", "name":"category-detail", "componentClass":"org.hippoecm.hst.core.component.GenericHstComponent", "type":"COMPONENT", "components":[ { "id":"r39_r1", "name":"main", "componentClass":"com.bloomreach.commercedxp.starterstore.components.GenericCommandChainComponent", "type":"COMPONENT", "models":{ "compositeBean":{ "displayName":"Womens", "descriptionHtml":null, "imageSet":null, "id":"kzcvgvcsjfpucucqifjektc7k5hu2rkokm=", "children":[ //...SNIP... ] }, "document":null }, "components":[ //...SNIP... ], //...SNIP... }, //...SNIP... ], "_meta":{ "definitionId":"hst:pages/category-detail", "params":{ } }, //...SNIP... }, "content":{ //...SNIP... } }
In this example, the "main" HST Component adds a CategoryModel named "Womens." The Delivery API at http://localhost:8080/site/fr/resourceapi/categories/... returns the JSON representation of the CategoryModel in the models section of the component. The component provides the CategoryModel by calling HstRequest#setModel("compositeBean", categoryModel);.
Product-Related Components (Product Grid Example)
When a page includes product-related HST Components, such as "Product Grid" or "Product Detail," the component contributes the relevant ItemLike (ItemModel or ItemVariant) objects to the Delivery API. The following example demonstrates the API response structure:
{ "id":"r37", "_links":{ "self":{ "href":"http://localhost:8080/site/resourceapi/product-grid" }, "site":{ "href":"http://localhost:8080/site/product-grid" } }, "page":{ "id":"r37", "name":"product-grid-flexpage", "componentClass":"org.hippoecm.hst.core.component.GenericHstComponent", "type":"COMPONENT", "components":[ { "id":"r37_r1", "name":"main", "componentClass":"org.hippoecm.hst.core.component.GenericHstComponent", "type":"COMPONENT", "components":[ { "id":"r37_r1_r1", "name":"top", "componentClass":"org.hippoecm.hst.builtin.components.StandardContainerComponent", "type":"CONTAINER_COMPONENT", "label":"Flexible Top Container", "components":[ { "id":"r37_r1_r1_r1", "name":"ProductGridSearch", "componentClass":"com.bloomreach.commercedxp.starterstore.components.GenericCommandChainComponent", "type":"CONTAINER_ITEM_COMPONENT", "label":"Product Grid (Search)", "models":{ "pageable":{ "pageSize":9, "visiblePages":10, "total":3, "showPagination":true, "items":[ { "displayName":"Levana Digital Baby Video Monitor, Stella", "descriptionHtml":null, "imageSet":{ "variants":{ "0":{ "dimension":{ "width":0, "height":0 }, "links":{ "self":{ "href":"https://images-na.ssl-images-amazon.com/images/I/41xapWVs3RL.jpg", "ref":null } } } } }, "attributes":{ "reviews":"3.9", "brand":"Levana", "reviews_count":"175" }, "variants":[ { "attributes":{ "reviews":"3.9", "brand":"Levana", "reviews_count":"175" }, "itemId":{ "id":"var1-b77cbf85-9447-48e9-8e9b-d7396e65a9a8", "code":"p10277" }, "displayName":"Levana Digital Baby Video Monitor, Stella", "description":"Levana Stella Digital Baby Video Monitor with Pan/Tilt/Zoom and 4.3\" ScreenStella (S)tel-la)Meaning: StarStella showcases your little superstar on a large 4.3\" screen. You'll love Stella's whisper quiet pan/tilt/zoom (PTZ) camera, smart LED volume status indicator ring and battery life of up to 36 hours. Your baby will love the three soothing lullabies, invisible night vision LEDs and Talk to Baby intercom. With so many handy features plus a 750ft digital wireless range, Stella makes doing more at naptime a breeze.", "imageSet":{ "variants":{ "0":{ "dimension":{ "width":0, "height":0 }, "links":{ "self":{ "href":"https://images-na.ssl-images-amazon.com/images/I/41xapWVs3RL.jpg", "ref":null } } } } }, "listPrice":{ "moneyAmounts":[ { "amount":199, "currency":"USD", "displayValue":"USD 199.0" } ] }, "purchasePrice":{ "moneyAmounts":[ { "amount":199, "currency":"USD", "displayValue":"USD 199.0" } ] }, "itemType":{ "id":"", "name":"undefined" } } ], "description":"Levana Stella Digital Baby Video Monitor with Pan/Tilt/Zoom and 4.3\" ScreenStella (S)tel-la)Meaning: StarStella showcases your little superstar on a large 4.3\" screen. You'll love Stella's whisper quiet pan/tilt/zoom (PTZ) camera, smart LED volume status indicator ring and battery life of up to 36 hours. Your baby will love the three soothing lullabies, invisible night vision LEDs and Talk to Baby intercom. With so many handy features plus a 750ft digital wireless range, Stella makes doing more at naptime a breeze.", "itemType":{ "id":"", "name":"undefined" }, "itemId":{ "id":"b77cbf85-9447-48e9-8e9b-d7396e65a9a8", "code":"p10277" }, "listPrice":{ "moneyAmounts":[ { "amount":199, "currency":"USD", "displayValue":"USD 199.0" } ] }, "purchasePrice":{ "moneyAmounts":[ { "amount":199, "currency":"USD", "displayValue":"USD 199.0" } ] } }, { "displayName":"Levana Astra Digital Baby Video Monitor with LEVANA Powered by Snuza Oma Portable Baby Movement Monitor System...", "descriptionHtml":null, "imageSet":{ "variants":{ "0":{ "dimension":{ "width":0, "height":0 }, "links":{ "self":{ "href":"https://images-na.ssl-images-amazon.com/images/I/41XqnMkL-%2BL.jpg", "ref":null } } } } }, "attributes":{ "reviews":"3.3", "brand":"Levana", "reviews_count":"29" }, "variants":[ { "attributes":{ "reviews":"3.3", "brand":"Levana", "reviews_count":"29" }, "itemId":{ "id":"var1-816fb42e-3a40-4c6d-a648-7456b961a3ab", "code":"p10005" }, "displayName":"Levana Astra Digital Baby Video Monitor with LEVANA Powered by Snuza Oma Portable Baby Movement Monitor System...", "description":"When baby is finally quiet it should be a relief, not a worry. At LEVANA, we know how tempting it is to check on a soundly sleeping infant over and over again just in case. Astra and Oma work together to provide total peace of mind. See everything with a pan tilt and zoom camera and, when you're not looking, know that you will be alerted immediately if baby is not moving. Breathe easier knowing LEVANA Astra and Oma will be there to help you check in a little less and relax a little more.", "imageSet":{ "variants":{ "0":{ "dimension":{ "width":0, "height":0 }, "links":{ "self":{ "href":"https://images-na.ssl-images-amazon.com/images/I/41XqnMkL-%2BL.jpg", "ref":null } } } } }, "listPrice":{ "moneyAmounts":[ { "amount":199, "currency":"USD", "displayValue":"USD 199.0" } ] }, "purchasePrice":{ "moneyAmounts":[ { "amount":199, "currency":"USD", "displayValue":"USD 199.0" } ] }, "itemType":{ "id":"", "name":"undefined" } } ], "description":"When baby is finally quiet it should be a relief, not a worry. At LEVANA, we know how tempting it is to check on a soundly sleeping infant over and over again just in case. Astra and Oma work together to provide total peace of mind. See everything with a pan tilt and zoom camera and, when you're not looking, know that you will be alerted immediately if baby is not moving. Breathe easier knowing LEVANA Astra and Oma will be there to help you check in a little less and relax a little more.", "itemType":{ "id":"", "name":"undefined" }, "itemId":{ "id":"816fb42e-3a40-4c6d-a648-7456b961a3ab", "code":"p10005" }, "listPrice":{ "moneyAmounts":[ { "amount":199, "currency":"USD", "displayValue":"USD 199.0" } ] }, "purchasePrice":{ "moneyAmounts":[ { "amount":199, "currency":"USD", "displayValue":"USD 199.0" } ] } }, //...SNIP... ], "maxSize":10, "startOffset":0, "endOffset":3, "next":false, "currentPage":1, "previousPage":null, "nextPage":null, "previous":false, "previousBatch":false, "nextBatch":false, "pageNumbersArray":[ 1 ], "endPage":1, "startPage":1, "totalPages":1, "currentRange":[ 1 ] } }, //...SNIP... } ], //...SNIP... }, //...SNIP... ], //...SNIP... }, //...SNIP... ], "_meta":{ "definitionId":"hst:pages/product-grid-flexpage", "pageTitle":"product-grid", "params":{ } }, //...SNIP... }, "content":{ //...SNIP... } } ..
In this example, the "ProductGridSearch" HST Component adds a Pageable ("pageable") collection of ItemLike objects. The Delivery API at http://localhost:8080/site/resourceapi/product-grid returns the JSON representation of the Pageable and its ItemLike objects in the models section of the component. The component provides the Pageable by calling HstRequest#setModel("pageable", pageable);.
Commerce Model JSON Mapping
Commerce Model objects—such as CategoryModel and ItemLike (ItemModel or ItemVariant)—are serialized to JSON using the Jackson library. When the Delivery API serializes HST Content Beans, it applies Jackson Mixin Types for a cleaner JSON output. Commerce Model objects also use built-in Jackson Mixin Types as shown below.
Hint: The package name
com.bloomreach.commercedxp.api.v2.connector.is abbreviated asc.b.c.a.v.c., andcom.bloomreach.commercedxp.starterstore.pagemodelapi.v2.connector.asc.b.c.s.p.v.c.in the table.
| Commerce Model Type | Mixin Type |
|---|---|
c.b.c.a.v.c.model.CategoryModel | c.b.c.s.p.v.c.model.jackson.CategoryModelMixin |
c.b.c.a.v.c.model.ItemLike | c.b.c.s.p.v.c.model.jackson.ItemLikeMixin |
c.b.c.a.v.c.model.ItemModel | c.b.c.s.p.v.c.model.jackson.ItemModelMixin |
c.b.c.a.v.c.model.ItemVariant | c.b.c.s.p.v.c.model.jackson.ItemVariantMixin |
c.b.c.a.v.c.model.ImageSetModel | c.b.c.s.p.v.c.model.jackson.ImageSetModelMixin |
c.b.c.a.v.c.model.ImageModel | c.b.c.s.p.v.c.model.jackson.ImageModelMixin |
Retrieving Model Objects in Your Application
Currently, every Commerce Model object is embedded in the models field. However, you should always check whether the object is referenced by a JSON Pointer or embedded directly. For details, see Introduction to the Delivery API.
Hint: For future compatibility, ensure your SPA checks whether a model is referenced by a JSON Pointer or embedded as content. Future versions may place Commerce Model objects in the top-level
contentfield for efficiency.