Route Resolver API Option

Overview

The Route Resolver API Option defines URL paths for each Document’s url property. The url property appears on:

Documents returned from the API
Documents linked internally from other Documents (such as in Content Relationship fields or links in Rich Text)

If no Route Resolver is specified, the url property will be null.

Example

This is an example Route Resolver for an international e-commerce website with a primary American locale (en-us) and a secondary French locale (fr-fr):

Copy

[
  {
    type: 'page',
    uid: 'homepage',
    path: '/lang?',
  },
  {
    type: 'page',
    path: '/:lang?/:uid',
  },
  {
    type: 'product',
    resolvers: {
      category: 'category',
      section: 'category.section',
    },
    path: '/:lang?/:section/:category/:uid',
  },
  {
    type: 'blog_post',
    locale: 'en-us',
    path: '/blog/:uid',
  },
]

Here is how each of those rules will work to resolve a URL:

Copy

{
  type: 'page',
  uid: 'homepage',
  path: '/:lang?',
}

For a “page” Document with the UID “homepage,” return the root (/), and include the locale only if it’s not the main locale. So, for the American locale the URL would be / and for the French locale the URL would be /fr-fr.

Copy

{
  type: 'page',
  path: '/:lang?/:uid',
}

For Documents of the type “page”, include the locale only if it’s the main locale; and, include the UID. For a Document with the UID “hello-world” in English and “bonjour-le-monde” in French, the paths are /hello-world and /fr-fr/bonjour-le-monde.

Copy

{
  type: 'product',
  resolvers: {
    category: 'category',
    section: 'category.section',
  },
  path: '/:lang?/:section/:category/:uid',
}

For a “product” Document, include the locale if it’s not the main locale, then include the section (from a grandparent document), the category (from a parent document), and the UID. For a “product” Document with the UID of “red-blouse” with a parent category of “tops”, and the parent category’s section of “clothing”, the path is /clothing/tops/red-blouse, while the corresponding French Document would have the path /fr-fr/vetements/chemises/chemisier-rouge.

Copy

{
  type: 'blog_post',
  locale: 'en-us',
  path: '/blog/:uid',
}

For a “blog_post” Document in the American locale, the URL is /blog/ and then the UID, such as /blog/my-first-post.

Usage

The Route Resolver is an API Option. To use it in an HTTP request, remove whitespace, encode the value, and, append it to the HTTP URL as described in the Rest API Technical Reference.

To use the Route Resolver with one of our development kits, like JavaScript, React, or Vue, see the documentation for your framework.

Only the path property is required; all others are optional.

type

The API ID for a specific Custom Type.

uid

Either the UID for a specific Document or * for any Document.

lang

Either a specific Locale Code or * for any Locale.

resolvers

The resolvers property is an object that defines parent and grandparent relationships that can be used as variables in the path property.

For example, A City Custom Type has a state property, which is a Content Relationship to a State Custom Type. The State Custom Type has a country property, which is a Content Relationship with a Country Custom Type. A Route Resolver would look like this:

Copy

{
  type: 'city',
  resolvers: {
    state: 'state',
    country: 'state.country',
  },
  path: '/:country/:state/:uid',
}

For the Sydney Document, the Route Resolver will return /australia/new-south-wales/sydney. For the Albany Document, the Route Resolver will return /united-states/new-york/albany.

Resolvers can access parent and grandparent properties. Resolvers cannot access great-grandparents or further.

path

A pattern for constructing each Route. The following variables are available:

:uid

The Document’s UID.

:lang

The Document’s Locale Code. If flagged as optional with a question mark (:lang?) this segment will be omitted for the master locale.

:resolver

Any resolver variable defined in the resolvers property, such as :state and :country in the example above. If marked as optional with a question mark (:resolver?) the segment will be omitted if it is not available.

Was this article helpful?

Not really

Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.