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):
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:
- An exact (explicit) match is considered more specific than any wildcard match
_default_
is more specific than_any_
_default_.html
is more specific than_default_
_any_.html
is more specific than_any_
_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.
Updated 10 days ago