HomeEngagementContentDiscoveryOther Resources
API Reference

Links

Link JSON representation

Link objects can appear at various places within the Delivery API's Pages endpoint response. For example, as top level element or as part of a component, content item or menu.

Internal, External, Resource, and Unknown

In the content section, the links object may contain a site link which specifies a type. The type are:

  • internal
  • external
  • resource
  • unknown

The type "internal" indicates the page can be represented within the current SPA. This means the SPA can use an XHR request and do a partial page update instead of making a full-page request. For example:

"links":{
  "site":{
    "href":"/site/myapp",
    "type":"internal"
  }
}

In the example above, the link to /site/myapp can be represented within the current SPA. The SPA may opt to make an XHR call, at /site/api/brxsaas/page/myapp for example, instead of making a full page request.

The type "external" indicates the link does not represent a frontend SPA link that can be rendered as a partial page update.

The type "unknown" is for links to some resource that cannot be found (for example it is possible that some document or asset gets linked by a document for the current URL but that linked document cannot be fetched by a URL. The HST in that case returns a 'not-found-link', the Page Model API translates this into "unknown". An SPA implementation can decide what to do with the value.

Finally, the type "resource" is used for a reference to a binary resource (image or asset) from Content SaaS or an external binary storage.

Because an SPA can only handle internal links as partial updates, a link of type "internal" is always a relative link, while the types "external" and "resource" always result in fully qualified URLs.

Links in rich text content

Serialized documents may contain rich text fields. When rich text fields are serialized to JSON, its HTML contents are rewritten to make sure that images and links are accessible and usable from the SPA. For example, when a document contains a link in a rich text field to another document, the link is rewritten to more accessible and usable markup. See the following example:

<a href="/news/news1.html" data-type="internal"/>

The SPA retrieves the href attribute which it can directly navigate to or, optionally, it can do something smarter with it:

If the data-type is "internal", then the link can be used as an XHR call (typically something like /resourceapi/news/news1.html) which updates part of the page, instead of making a new page request.

If, however, the data-type is "external", then the SPA should always do a full-page request (never an XHR call) because the linked page cannot be displayed within the current SPA. Typically this happens in one of the following cases:

  • There is a hybrid setup with SPA pages and the link represents a normal server side rendering page.
  • The link belongs to a document that is part of a different channel which is not part of the SPA.

The data-type can also be "resource" indicating that the href points to a binary.

Maximum content item reference depth level

As explained in Components, if a content item is referred to by a component, the content item will be included in the flattened response. In this case, the reference depth level is 1, meaning that the content item is in the first reference depth level from the component.

Now, suppose the specific content item also has a reference to another content item. The second referenced content item is in reference depth level 2 from the component. Any referenced content item in the second or any deeper level will not be included in the top-level content field, by default, unless another component has a direct reference to it. So, the first content item representation will include only a JSON pointer reference to the second content item. The maximum content item reference depth level is set to 1 in the system, by default. If the maximum depth is reached, the reference will be serialized as the JSON pointer from which the UUID of the referenced document can be deducted by the SPA and a separate request could be made to fetch only that content (note that we do not yet have support for this latter but is identified as a feature to support

How to include up to level N referenced content items?

🚧

Increasing the maximum content item reference depth has a negative impact on performance. Bloomreach strongly recommends keeping the default maximum content reference level at the default value of 1.

You can change the maximum content item reference depth level per request by adding the  _maxreflevel request parameter as follows:

  • http://localhost:8080/site/myapp/resourceapi/news/?_maxreflevel=2

The response will include referenced content items in up to depth level 2.