Content HAL API

Info: Bloomreach provides Enterprise support for this feature for Bloomreach Experience customers. The release cycle for this feature may differ from the core product release cycle.

Overview

The Content HAL API add-on exposes JSON Hypertext Application Language (HAL) based REST APIs from your delivery applications.

JSON Hypertext Application Language (HAL) is a draft specification for HATEOAS (Hypermedia as the Engine of Application State), a REST architectural constraint. HAL services return responses in the application/hal+json media type. The HAL specification uses plain JSON, focusing on generality and simplicity.

Swagger API Documentation

The Content HAL API add-on automatically provides a Swagger API documentation endpoint. If you install the Content HAL API on the /api mount (for example, http://localhost:8080/site/api), the Swagger API documentation is available at /api/api-docs/swagger.json (for example, http://localhost:8080/site/api/api-docs/swagger.json). You can use this endpoint with a Swagger UI web application to explore the Content HAL API.

Content HAL API URL Patterns

Refer to the API documentation for details on accessing the REST APIs.

HAL Resource Structure

The Content HAL API add-on ensures that every response is a HAL resource.

Minimal HAL Resource Example

A minimal HAL resource is represented as an empty JSON object:

{
}
copy

Typical HAL Resource Example

A typical HAL resource includes at least a self link in the reserved _links property:

{
  "_links": {
    "self": { "href" : "/orders/523" }
  }
}
copy

This resource contains a link to itself.

In practice, HAL resources often include additional fields:

{
  "_links": {
    "self": { "href": "/orders/523" },
    "invoice": { "href": "/invoices/873" }
  },
  "currency": "USD",
  "status": "shipped",
  "total": 10.20
}
copy

A HAL resource can contain any properties (such as currency, status, total) alongside links in the reserved _links property, as long as the structure is valid JSON.

HAL Resource with Embedded Resources

A HAL resource can embed other resources. The embedded resources may contain all or part of their fields:

{
  "_links": {
    "self": { "href": "/orders" }
  },
  "_embedded": {
    "orders": [{
        "_links": { "self": { "href": "/orders/523" } },
        "total": 30.00
      },{
        "_links": { "self": { "href": "/orders/524" } },
        "total": 20.00
      }]
  },
  "currentlyProcessing": 14,
  "shippedToday": 20
}
copy

For example, a response from http://localhost:8080/sales/orders may include order collection data under the _embedded property, along with other fields.

Mapping Hippo Documents to HAL Resources

The Content HAL API add-on maps Hippo documents to HAL resources by using the logical field names defined in the document type (namespace) configuration.

The following diagram illustrates how fields in the "Event" document type map to namespace node type paths:

Diagram: The image shows how fields in the Event document type editor (such as Title, Introduction, Content, Start date, End date, and Location) correspond to logical field names in the namespace definition. The arrows indicate the mapping between editor fields and entries in the namespace tree under hippo:namespaces > frontend > hippo > hippoaddoncontenthalapidemo > eventsdocument > hipposysedit:nodetype.

The "Event" document type defines fields such as title, introduction, content, startdate, enddate, and location. The "Path" configuration specifies the logical field names (for example, title, introduction, content), which are distinct from the display captions ("Title", "Introduction", "Content").

In the CMS Console, these "Path" configurations are stored in the hipposysedit:nodetype/hipposysedit:nodetype configuration within the document type (namespace) definition.

Since captions are for display only, the Content HAL API uses the logical field names from the "Path" configuration as JSON property names in the HAL resource. The following diagram shows this mapping:

Diagram: The diagram shows a document type structure on the left and a JSON HAL resource on the right. Arrows connect field names in the document type to matching JSON properties in the HAL example. The JSON includes a reserved _links section with a self link, showing how document content and HAL links appear together.

An "Event" document is represented as a JSON HAL resource by converting each field to a JSON property using the logical field names from the "Path" configuration. The resource also includes links under the reserved _links property, such as a self link generated by the HST-2 API.

Handling Compound Fields (RichText)

Compound fields, such as the content field of type hippostd:html, are mapped by converting each property of the compound node type into a JSON object. The following example illustrates this mapping:

Diagram: The diagram shows a JCR repository tree on the left and a HAL-style JSON representation on the right. The highlighted hippostd:html node and its content property are mapped to a JSON content object that contains a _meta property with type: "hippostd:html" and a nested content string value. The _meta property carries Hippo-specific metadata for the document or compound.

The hippostd:html node type contains a content property. The Content HAL API expands the content field into a JSON object with a content property (string value) and a _meta property for metadata.

Note: In this example, both the document and the compound node type use the name content. If you rename the field in the document type (for example, to body), the JSON property name will reflect that change.

Representing Linked Images, Assets, or Documents

Fields such as image in an "Event" document may link to other CMS image asset nodes. These fields typically contain link information (hippo:docbase), which is CMS-specific. The Content HAL API includes this metadata in the reserved _meta property.

All CMS-specific metadata is included in the _meta property. This property may contain the JCR primary type name (type) and link information in a mirror object (including both node UUID and node path). The _meta property is an extension introduced by the Content HAL API add-on.

Including Site Links

By default, a HAL resource includes a self link for a document, for example:

{
  "_links": {
    "self": {
      "href": "http://localhost:8080/site/api/documents/18e36c35-429d-4fee-b76e-eeabcbfc08bb"
    }
  }
}
copy

To include a site link in addition to the self link:

{
  "_links": {
    "self": {
      "href": "http://localhost:8080/site/api/documents/18e36c35-429d-4fee-b76e-eeabcbfc08bb"
    },
    "site": {
      "href": "http://localhost:8080/site/events/2019/01/introduction-speech.html"
    }
  }
}
copy

Configure the HST-2 mount alias mapping as follows:

1. Set the hst:alias property of the parent mount (for example, /hst:root) of the Content HAL API mount (for example, /hst:root/api) to site:
   • /hst:root/@hst:alias="site"
2. Add the hst:mountsite property (String) with the value site to the Content HAL API mount (for example, /hst:root/api):
   • /hst:root/api/@mountsite="site"

With this configuration, the Content HAL API can resolve the parent mount via the mapping (@hst:mountsite="site") to the mount with @hst:alias="site" (for example, /hst:root). The API then generates the site link and includes it in the _links property.