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 the Accept-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 global default.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 the Delivery 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 the Delivery API mount becomes available automatically at the configured mount path + / + resourceapi. e.g, /resourceapi, /myapp/resourceapi, etc. You don't need to configure the resourceapi 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 are mapped (@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 or myapp). 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 to SpaSitePipeline for your Single Page Application. A mount with @hst:namedpipeline=SpaSitePipeline will render only the root 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 id="root">
</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 invoke Delivery 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 of Delivery 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 from Delivery 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 - including CORS headers - at virtual host, mount, or even sitemap 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 at virtual 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 value true).
- If the Access-Control-Allow-Origin response header is defined in the @hst:responseheaders property, the @hst:allowedorigins property is ignored.
- The hst:allowedorigins property is available since Bloomreach Experience Manager 14.1.0. If your implementation project is on 14.0, you must upgrade to 14.1 in order to use hst: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 property hst:linkurlprefix either at virtual host or mount 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 the hst:root mount (or its submounts, if any) will be prefixed with the configured prefix https://www.example.org/foo instead of the matched 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.