Routes - Bloomreach Experience - Headless Digital Experience Platform

Routes

Definitions

A route binds a URL or URL range to a layout and, optionally, to a content path relative to the content root defined for the channel.

Together, the routes in a site configuration define the URL path structure of the site and the patterns of how Delivery API's Pages endpoint request URLs map to content and layouts to generate full pages.

The basic idea behind routing is to provide flexible rules for matching specific URLs or complete URL spaces and map URLs on layouts. The routing configuration is a composite structure containing a hierarchy of routes. It can contain routes with explicit names or with wildcards matching to any name.

The following wildcards are supported (with a path segment defined as a part of a URL between two slashes):

Wildcard Description
_default_ Matches any single path segment. Comparable to a single asterisk (*) in a Unix glob pattern.
_any_

Matches multiple path segments at the end of a URL. Comparable to a double asterisk (**) in a Unix glob pattern.

Only allowed as leaf route element.

_default_.ext

Matches any single path segment ending with "ext", where "ext" can be any extension.

For example: _default_.html

_any_.ext

Matches any single path segment ending with "ext", where "ext" can be any extension.

For example: _default_.html

Only allowed as leaf route element.

During the routing phase, the URL is attempted to be matched to the best route. The best route is the one that matches earliest path segments more specifically according to the following rules:

  1. An exact (explicit) match is considered more specific than any wildcard match
  2. _default_ is more specific than _any_
  3. _default_.html is more specific than _default_
  4. _any_.html is more specific than _any_
  5. _default_ is more specific than _any_.html

When defining routes using a wildcards, developers can use variables such as ${1}, ${2}, etc. which will be resolved to the path segments matched by the wildcards. Typically these variables are used to match a URL to a specific content item to be rendered using a generic layout.

For example, consider the Articles section in the sample application. Let's take it apart step by step.

If you browse this section in the sample frontend application, you'll notice the URLs are as follows:

  • /articles (articles overview page)
  • /articles/torque-wrench-basics (article page)
  • /articles/changing-a-tap-washer (article page)
  • /articles/highlighted/what-is-a-flange-nut (article page)
  • etc.

I you browse the brX Content application, you'll find the matching content at the following locations:

  • BrX SaaS/pages/Articles ("Content" experience page document)
  • BrX SaaS/articles/Torque Wrench Basics ("Content" document)
  • BrX SaaS/articles/Changing a Tap Washer ("Content" document)
  • BrX SaaS/articles/highlighted/What is a Flange Nute? ("Content" document)
  • etc.

Finally, if you retrieve the articles route configuration through the Site Management API, you'll receive the following JSON representation:

{
    "name": "articles",
    "layout": null,
    "pageTitle": null,
    "relativeContentPath": "pages/articles",
    "referenceId": null,
    "parameters": {},
    "doctypePages": {},
    "items": [
        {
            "name": "_any_",
            "layout": "content",
            "pageTitle": null,
            "relativeContentPath": "content/articles/${1}",
            "referenceId": null,
            "parameters": {},
            "doctypePages": {},
            "items": []
        }
    ]
}

The top level route element, articles, maps the /articles URL to the "Articles" experience page document in the "pages" folder. Since experience pages have their layout embedded, the route does not need to specify a layout, hence the layout property is null.

The nested _any_ route element maps the URLs for the individual articles (/articles/torque-wrench-basics, /articles/changing-a-tap-washer, /articles/highlighted/what-is-a-flange-nut, etc.) to the content layout and the content path matching the URL. The ${1} variable in the content path is resolved to the path segment(s) resolved by the _any_ wildcard (torque-wrench-basics, changing-a-tap-washer, highlighted/what-is-a-flange-nut, etc.). This way, any article inside the "articles" folder (or any of its subfolders) automatically has a corresponding URL in the site using the generic content layout.

For an overview of all route element properties, see the Route schema in the Site Management API reference documentation.

Operations

The Site Management API treats each top-level route element and all of its children as a single entity, so that an entire section of a site can be defined in a single request. Thus, the API provides a coarse grained management approach and changes to nested routes can only happen by updating the top level route. For updates, a GET request is usually executed first, to retrieve the whole hierarchy of a top level route (and also the latest X-Resource-Version header).

See Channel Route Operations in the Site Management API reference documentation for a list of operations.

You can find examples of using the route endpoints in the Postman collection.

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?