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.

Wildcard matchers

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

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 Reference SPA. Let's take it apart step by step.

If you browse this section in the 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.

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

• [channel name]/pages/Articles ("Content" experience page document)
• [channel name]/articles/Torque Wrench Basics ("Content" document)
• [channel name]/articles/Changing a Tap Washer ("Content" document)
• [channel name]/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.

Index matcher

Using wildcard matchers, developers can design part of the URL space of their website to map directly to a part of the content structure in the repository. Such a design will map to documents as well as folders. When mapping to a document, typically the document content should be rendered. When mapping to a folder, there are multiple options such as rendering a list of documents in that folder or rendering a default document. When rendering default content, it may even be required to fall back to rendering a list of documents in case the default document or folder does not exist in the mapped relative content.

The special _index_ matcher enables a flexible routes design that can handle such scenarios. Explicit routes and _default_ routes can have an _index_ child route which maps to a document or folder. Whenever a request matches a route with an _index_ child route, an attempt is made to map the request to the content path configured for the _index_ route. If that content path does not exist, the request is mapped to the content path configured for the originally matched sitemap item.

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.