Routing

Routing is the process of resolving a requested URL to render the appropriate content for that URL. Once a URL is published it acts as a contract with any visitor that content can be retrieved using it. Therefore it's important to make decisions about what system or URL management approach acts as the source of truth for URLs to confirm that they're consistent and valid.

In Uniform, URLs are primarily generated through a project map and resolved through the Route API . The Route API enables fetching dynamic and static project map paths, as well as handling redirects with a single API endpoint. You can use the Route API by using framework-specific helpers, SDK (RouteClient), or by calling the Route API directly.

Project map routes#

A project map has a tree of nodes that define the URL structure for your project (often a web page). Use project map routes when Uniform is the primary source of truth for URLs.

By using project maps you can manage, visualize, and resolve URLs for compositions that are managed in Uniform (by attaching compositions to nodes) or in other systems (by using placeholder nodes or dynamic routes).

Use project map routes when:

• Uniform Canvas is responsible for defining and resolving most of your URLs
• Your application has nested URLs or views
• Your application has more than a few pages or views
• You want to empower business users to define URL structures
• The URL structure contains dynamic elements such as product IDs

Use these tools to implement routing with project maps:

• Recommended: The Route API enables fetching dynamic and static project map paths, as well as handling redirects, with a single endpoint. Uniform provides framework-specific helpers, RouteClient, or the Route API .
• The ProjectMapClient and project map API provide management of project map data, as well as querying by static project map paths.
• The CanvasClient can fetch compositions based on static project map paths (dynamic path segments are only supported using the Route API).

Dynamic routes#

Most applications need flexible routing where parts of the URL can vary dynamically—such as product IDs, search parameters, or locale codes. Uniform provides dynamic inputs to capture these variable values from URLs and pass them to compositions.

Dynamic route matching#

With dynamic routes it can happen that more than one project map node matches a given input path. For example, the path /products/132 could match both /products/:productId or /products/132 in a project map. Redirects defined in Uniform could also match a path from a project map node and the redirect.

When multiple possible matches occur:

• Redirect matches override project map matches.
• More specific project map or redirect paths win. Meaning, the candidate with the fewest dynamic path segments wins. In the preceding example /products/132 is an exact match and so it wins.
• Matches use the whole path and don't evaluate ancestors. For example, if you add /products/:productId/specs to the project map in the example, and request /products/132/specs, it will match even though product 132 has a custom project map node.

If you are attempting to figure out why a route isn't matching, note that the Route API returns the matched route in its response that you can inspect.

Localized routes#

Localized routes enable you to create locale-specific URL paths for static project map nodes. This is important for SEO and user experience as it allows you to adapt URLs to the language and cultural preferences of specific markets or regions.

For example, a product page might have:

• /en-US/products for English (US)
• /de-DE/produkte for German
• /fr-FR/produits for French

Each of these routes points to the same project map node but uses a different path segment based on the locale.

How localized routes work#

When a route is resolved with the Uniform Route API, it will match all possible routes for the given path, including localized routes for the requested locale. If a node has no localized path segment for the requested locale, the fallback (default) path segment of the node will be used.

If the requested route is able to resolve a matching locale on the attached composition, then the composition is returned in the requested locale. If the composition does not have a matching locale enabled, a "404 Not Found" response is returned.

Automatic redirects for localized routes#

If a route contains the fallback path segment of a localized node, it will automatically redirect to the localized path segment for that locale.

For example, if you have a project map node /products with a localized path segment /produkte for the German de-DE locale, and a request is made to /de-DE/products, the Route API will return a redirect result to /de-DE/produkte automatically.

This ensures that you can safely start with non-localized routes and add localized routes later without breaking existing URLs.

Configure localized routes#

To configure localized routes:

1. Localize individual nodes in your project map by defining locale-specific path segments for each locale.
2. Optionally, set up a locale node to capture the locale from the URL for locale resolution.

Learn more about localization in Uniform.