## 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):

`_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 [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:

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](🔗).