Configure Delivery API

Overview

To enable the Delivery API (formerly Page Model API) in the delivery tier, configure the Delivery API path on a Mount or SiteMapItem. This configuration allows the delivery tier to serve the initial Single Page Application (SPA) page.

If your SPA is served directly from a CDN or a Node.js server (not from the delivery tier web application), you do not need to configure a Mount or SiteMapItem for the initial SPA page.

Configure the Delivery API Version (brXM 14.3–14.7)

Info: Available in brXM 14.3.0 and later.

Info: brXM 15 only supports Delivery API version 1.0. Version 0.9 is not available in version 15.

brXM 14.3.0 introduced Delivery API version 1.0, which changes the structure of the JSON response data. For backward compatibility, version 0.9 is enabled by default in all 14.x releases.

To enable Delivery API version 1.0, add the following property to your site web application's HST configuration properties file, typically located at site/webapp/src/main/webapp/WEB-INF/hst-config.properties:

default.pagemodelapi.version = 1.0

You can also specify the Delivery API version per request by setting the following header:

Accept-Version

Set the Accept-Version header to 1.0 to serve API version 1.0, or to 0.9 to serve version 0.9. If you specify a non-existent version, the API defaults to the global default.pagemodelapi.version setting.

Using the Accept-Version request header triggers preflight (OPTIONS) requests, which may reduce frontend performance. For optimal performance, configure the Delivery API version using the default.pagemodelapi.version property whenever possible.

Configure the Delivery API

To configure the Delivery API, add the @hst:pagemodelapi property to a virtual host (hst:virtualhost) or mount (hst:mount) configuration node. The value of this property determines the path where the Delivery API child mount is available.

For example, if you set the @hst:pagemodelapi property on a mount (such as / or /myapp):

hst:pagemodelapi = resourceapi

The Delivery API mount becomes available at the mount path plus /resourceapi (for example, /resourceapi, /myapp/resourceapi). You do not need to configure the resourceapi mount separately.

If you set the @hst:pagemodelapi property on a virtual host (hst:virtualhost), all descendant mounts under that virtual host inherit the resourceapi child mount.

The Delivery API child mount is available only for mounts that are mapped (@hst:ismapped=true) and associated with a specific Channel.

Configure SPA Site Mount

If you serve SPAs through the delivery tier web application (not directly from Node.js or a CDN), configure an SPA Site Mount.

Assume you have a channel mapped to a mount (such as hst:root or myapp). To configure the mount as an SPA Site Mount, use 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

Set the @hst:namedpipeline property to SpaSitePipeline for your SPA. A mount with @hst:namedpipeline=SpaSitePipeline renders only the root HST component for a page URL (such as /, /news, /news/news1.html). The root HST component and its rendering template (Freemarker or JSP) should serve the HTML that loads your SPA. For example:

<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>

After this configuration, your SPA can call the Delivery API on the /resourceapi child mount (such as /resourceapi, /resourceapi/news, /resourceapi/news/news1.html), as specified by the @hst:pagemodelapi property.

You can change the value of the @hst:pagemodelapi property from the default (resourceapi) to another value to modify the Delivery API endpoint. If you do, ensure your SPA uses the updated endpoint.

Configure SPA Channel

Configuring an SPA Channel is the same as configuring other channels. Refer to the Experience manager documentation for details. The Experience Manager SPA Integration feature is available only to Bloomreach Content customers.

Configure CORS Response Headers

If your SPA runs on an external server and needs to consume JSON resources from the Delivery API in the HST delivery web application, you must configure the appropriate CORS response headers. This is required when the SPA and the Delivery API are on different domains.

You can configure custom response headers, including CORS headers, at the virtual host, mount, or sitemap item level by setting the @hst:responseheaders (string multiple) property. For example, you can set the Access-Control-Allow-Origin header to a specific host or to * to allow any origin.

Alternatively, use the @hst:allowedorigins property at the virtual host level to allow multiple origins. When a cross-origin request is made from an allowed origin, the Access-Control-Allow-Origin response header is automatically set to that origin.

The table below summarizes common use cases and the required CORS configuration:

Delivery API Use CaseCORS Configuration
Do not allow any cross-origin Delivery API requestsDefault, no additional configuration needed.
Allow Delivery API requests from any originhst:responseheaders: ["Access-Control-Allow-Origin: *"]
Allow Delivery API request from one specific originhst:responseheaders: ["Access-Control-Allow-Origin: http://www.example.com"]
Allow Delivery API requests from one or more allowed originshst:allowedorigins: ["http://www.example.org", "http://www.example.com"]

Notes:

  • For cross-origin Delivery API requests from an allowed origin, the Access-Control-Allow-Credentials response header is always set to true.
  • If you define the Access-Control-Allow-Origin response header in the @hst:responseheaders property, the @hst:allowedorigins property is ignored.
  • The hst:allowedorigins property is available from brXM 14.1.0. If you are using version 14.0, upgrade to 14.1 to use this property.

Info: Available in brXM 14.2.1 and later.

In some scenarios, such as when a client accesses the Delivery API through a reverse proxy, you may need to rewrite fully qualified links in the response so they are accessible to the client.

To do this, configure the hst:linkurlprefix property at the 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 this example, all links of type resource or external served from the hst:root mount (and its submounts, if any) are prefixed with https://www.example.org/foo instead of the matched host.

Note: If you configure hst:linkurlprefix on a submount, it does not apply to binary links. Binary links are always served from the root mount.

Share Feedback
Page: /frontend/page-model-api/configuration
Section: Frontend
Category *