Configure Delivery API
Introduction
In order to enable the Delivery API (formerly Page Model API) in the delivery tier, you must configure the path of the Delivery API on a Mount or SiteMapItem(s) to serve the initial SPA page.
If you choose to serve your SPA from a CDN or a Node.js server directly (i.e. not from our delivery tier web application) then it is not needed to configure a Mount or SiteMapItem to serve the initial SPA page.
Configure the Delivery API Version (brXM 14.3-14.7)
Bloomreach Experience Manager 14.3.0 introduced version 1.0 of the Delivery API, making significant changes to the structure of the JSON response data. For backward compatibility, version 0.9 of the Delivery API is enabled by default in all 14.x releases.
To enable the Delivery API 1.0, add the following line to your site webapp's HST configuration properties file, typically at site/webapp/src/main/webapp/WEB-INF/hst-config.properties:
default.pagemodelapi.version = 1.0
Alternatively, instead of switching the default version globally for an entire site webapp, the desired Delivery API version can also be specified per request through the following header:
Accept-Version
Adding theAccept-Version header with value 1.0 serves API version 1.0, setting 0.9 serves API version 0.9. A non-existing version will default to the globaldefault.pagemodelapi.version.
Configure the Delivery API
Configuring the Delivery API requires adding a single property,@hst:pagemodelapi, to a virtual host (hst:virtualhost) or mount (hst:mount) configuration node. The value of the property will be the path on which theDelivery API child mount becomes available. For example, if the @hst:pagemodelapi property is configured like the following on a mount (hst:mount) configuration node (for mount path like/,/myapp, etc.), then theDelivery API mount becomes available automatically at the configured mount path +/ +resourceapi. e.g,/resourceapi,/myapp/resourceapi, etc. You don't need to configure theresourceapi mount underneath explicitly.
hst:pagemodelapi = resourceapi
If the@hst:pagemodelapi property is configured on a virtual host (hst:virtualhost) configuration node, all the descendant mounts under the virtual host will get the resourceapi child mount automatically.
Note that the Delivery API child mount becomes available only for the mounts that aremapped (@hst:ismapped=true)and associated with a specific Channel.
Configure SPA Site Mount
When you serve SPAs through our delivery tier web application, not from node.js or CDN directly, you should configure an SPA Site Mount.
Suppose you have a channel which is mapped to a mount (e.g,hst:root ormyapp). You can make the mount an SPA Site Mount as in the following example:
/hst:myproject/hst:hosts/dev-localhost/localhost/hst:root/myapp: jcr:primaryType: hst:mount hst:mountpoint: /hst:hst/hst:sites/myapp hst:namedpipeline: SpaSitePipeline hst:pagemodelapi: resourceapi
First, set@hst:namedpipeline property toSpaSitePipeline for your Single Page Application. A mount with@hst:namedpipeline=SpaSitePipeline will renderonly theroot HST component for a page URL (e.g,/,/news,/news/news1.html, etc.). The resolved root HST component and its rendering template (ftl or jsp) should serve the HTML that fetches your SPA. For example, it could serve something like the following:
<html lang="en"> <head> <title>React App</title> </head> <body> <noscript> You need to enable JavaScript to run this app. </noscript> <div> </div> <footer> <p>© 2018 BloomReach, Inc.</p> </footer> <script> // load React app from local Node server $.getScript( "http://localhost:3000/static/js/bundle.js" ) .fail(function() { // fallback to bundled React app in webfiles $.getScript( "/site/js/react-example-app.js" ); }); </script> </body></html>Afterward, your SPA is able to invokeDelivery API on the /resourceapi child mount (e.g,/resourceapi,/resourceapi/news,/resourceapi/news/news1.html, etc.), as configured by the @hst:pagemodelapi property.
You can also change the value of @hst:pagemodelapi property from the default value (resourceapi) to something else to change the endpoint ofDelivery API, but in that case make sure your Single Page Application uses the new Delivery API endpoint.
Configure SPA Channel
There is no difference in configuring an SPA Channel from other channels. Please follow the Experience manager documentation. However, please note that the Experienace Manager SPA Integration feature is available only to Bloomreach Experience Manager customers.
Configure CORS Response Headers
You may want SPAs on an external server to consume JSON resources from the Delivery API. For example, you could run an external node.js server for SPAs which needs to consume JSON resources fromDelivery API residing in the HST delivery web application. As those reside in different domains, the appropriate CORS response headers must be set by the HST delivery tier web application.
HST allows configuring additional custom response headers - includingCORS headers - at virtual host,mount, or evensitemap item level, by setting the@hst:responseheaders (string multiple) property. This way you can set the Access-Control-Allow-Origin response header to a single host or to '*' to allow any origin.
Alternatively, the @hst:allowedorigins property enables allowing multiple origins atvirtual host level. This way, if a cross-origin request is made from an allowed origin, the Access-Control-Allow-Origin response header is automatically set to that origin.
As a guideline, consider the table below listing four typical use cases and their required CORS configurations:
| Delivery API Use Case | CORS Configuration |
|---|---|
| Do not allow any cross-origin Delivery API requests | Default, no additional configuration needed. |
| Allow Delivery API requests from any origin | hst:responseheaders: ["Access-Control-Allow-Origin: *"] |
| Allow Delivery API request from one specific origin | hst:responseheaders: ["Access-Control-Allow-Origin: http://www.example.com"] |
| Allow Delivery API requests from one or more allowed origins | hst:allowedorigins: ["http://www.example.org", "http://www.example.com"] |
Note that:
- For cross-origin Delivery API requests from an allowed origin, the Access-Control-Allow-Credentials response header is always set (to its only valid valuetrue).
- If the Access-Control-Allow-Origin response header is defined in the@hst:responseheaders property, the @hst:allowedorigins property is ignored.
- Thehst:allowedorigins property is available since Bloomreach Experience Manager 14.1.0. If your implementation project is on 14.0, you mustupgrade to 14.1 in order to usehst:allowedorigins.
Configure Link URL Prefix
In some use cases, for example when a client is accessing the Delivery API through a reverse proxy, fully qualified links included in the response need to be rewritten to be accessible to the client.
For this purpose, a URL prefix can be configured in the propertyhst:linkurlprefix either atvirtual host ormount level.
Example:
/hst:myproject/hst:hosts/dev-localhost/localhost/hst:root: jcr:primaryType: hst:mount hst:homepage: root hst:mountpoint: /hst:myproject/hst:sites/myproject hst:pagemodelapi: resourceapi hst:linkurlprefix: https://www.example.org/foo
In the example above, all links of type 'resource' or 'external' served from thehst:root mount (or its submounts, if any) will be prefixed with the configured prefix https://www.example.org/foo instead of thematched host.
Please note that an hst:linkurlprefix configured on a submount does not apply to binary links because those are always served from the root mount.