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)

This feature is available since Bloomreach Experience Manager 14.3.0.
Bloomreach Experience Manager 15 no longer supports Delivery API version 0.9 and always serves version 1.0.

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.

Specifying the Delivery API version using the Accept-Version request header results in preflight (OPTIONS) requests and, consequently, possibly degraded frontend performance. We therefore strongly recommend to specify the Delivery API version using the default.pagemodelapi.version HST configuration property whenever possible.

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>&copy; 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

This feature is available since Bloomreach Experience Manager 14.2.1.

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.

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?