Delivery API Support
Introduction
Bloomreach Commerce Accelerator provides a built-in support for SPA (Single Page Application) by contributing Commerce Model objects to the Delivery API pipeline by default. SPA applications can read Commerce Model objects such as CategoryModel or ItemLike (ItemModel or ItemVariant) in JSON to render them in their UI components.
Commerce Model objects are serialized into JSON by the convention of standard Java Bean Properties. That is, CategoryModel#getId() property is serialized to "id" JSON property, CategoryModel#getDisplayName() property to "displayName" JSON property, and so forth. See Introduction to Commerce Connector SDK for detail on Commerce Model designs.
Example Delivery API Responses
Category related HST Components
If a page contains commerce category related HST Components such as "Category Highlight", then the component contributes the related CategoryModel to the Delivery API by default like the following example.
{
"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 the above example, the "main" HST Component contributes a CategoryModel called "Womens", so the Delivery API at http://localhost:8080/site/fr/resourceapi/categories/... responds with a JSON representation of the CategoryModel in the "models" section of the component. In other words, the specific component contributes the CategoryModel by invoking HstRequest#setModel("compositeBean", categoryModel);
Product related Components such as Product Grid
If a page contains commerce product related HST Components such as "Product Grid" or "Product Detail", then the component contributes the related ItemLike (ItemModel or ItemVariant) objects to the Delivery API by default like the following example.
{
"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 the above example, the "ProductGridSearch" HST Component contributes a Pageable ("pageable") of ItemLike objects, so the Delivery API at http://localhost:8080/site/resourceapi/product-grid responds with a JSON representation of the Pageable and ItemLike objects in the "models" section of the component. In other words, the specific component contributes the Pageable ("pageable") of ItemLike objects by invoking HstRequest#setModel("pageable", pageable);
Commerce Model JSON Mapping Details
Commerce Model objects, such as CategoryModel or ItemLike (ItemModel or ItemVariant), are serialized into JSON using the Jackson library. When Delivery API serializes HST Content Beans, it applies built-in Jackson Mixin Types to make a cleaner JSON output. Likewise, Commerce Model objects are also serialized using built-in Jackson Mixin Types like the following.
| 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 |
Best Practice to Retrieve Model Objects in Application
Even if every Commerce Model object as a model is embedded inside the models field at the moment, it is recommended to check whether it is referenced by a JSON Pointer reference or embedded with the real content in principle. See the Introduction to the Delivery API page for more detail.