Routing

This page gives you an introduction to the concept of routing. Go to schema references to find the API documentation for routing.

You can do routing by either Url or Handle.

URL

If you want your schema to be routable by an URL, you can specify the url as an expression. If we take a look at this example we can see that we have a Url property available in the Data Source

Source entity example

{
  "id": "1044-en-us",
  "type": "frontPage",
  "url": "/frontPage",
  "properties": {
    "title": "Welcome",
    "description": "description value"
  }
}

In the below example of the schema for this Data Source, we can see that the route is mapped to the url property on the Data Source. This means that you can get the data from this source by making a request to https://delivery.enterspeed.com/v1?url=/frontpage

/** @type {Enterspeed.FullSchema} */
export default {
  triggers: function(context) {
    context.triggers('umbraco', ['frontPage'])
  },
  routes: function(sourceEntity, context) {
    context.url(sourceEntity.url)
  },
  properties: function (sourceEntity, context) {
    return sourceEntity.properties
  }
}

What does “No environment client configured to support domain name for source entity url /relative-url/” mean?If you are using relative URLs (e.g. /about-us/) and are trying to test the schema by making a CURL request, you might have seen this error message.The reason for this is that the URL doesn’t have a domain that matches an environment client. Environment clients need to be able to match the URL in the source entity with the hostname provided for the environment client.The best way to solve this is to use absolute URLs in your schema (e.g. https://my-domain.com/about-us/).If you however want to use relative URLs, it can be done by adding a domain to your environment client with the hostname root.tld.

Your handles work, but your URL routes are missing?A URL route is only created if the hostname in the source entity’s URL is already registered as a hostname on a domain at the moment the content is processed. If no matching hostname exists at that point, the URL route is skipped, and no error is returned. Handles are not affected - handle routes are created regardless of your domain setup.Adding the domain afterwards does not create the missing routes. Nothing rebuilds routes for content that has already been processed. To fix it, register the hostname(s) first, then deploy the schemas in each affected environment so the content is reprocessed. A Published environment with its own data source needs its own deployment.This is not the same problem as the relative-URL message above, and the fixes are different:

Relative URLs (e.g. /about-us/) that can’t be matched - add the root.tld hostname. Note that root.tld is resolved when the content is processed, just like any other hostname, so content that was already processed without it still has to be processed again.
Absolute URLs whose routes were never created - root.tld won’t help. The actual hostname has to be registered on a domain, and the content has to be processed again afterwards.

See Domains & hostnames for the full explanation.

Handle

Handle differentiates a bit from URL routing. A handle can be whatever you would like. In this example, a navigation structure is returned. The schema returns an array of navigation items and utilizes the lookup and reference fields. This handle would be called like this: https://delivery.enterspeed.com/v1?handle=mainNavigation

/** @type {Enterspeed.FullSchema} */
export default {
  triggers: function(context) {
    context.triggers('umbraco', ['navigationGroup'])
  },
  routes: function(sourceEntity, context) {
    context.handle('mainNavigation')
  },
  properties: function (sourceEntity, context) {
    return {
      children: context.reference('navigationItem')
                          .children()
                          .orderBy({ 
                            propertyName: 'properties.metaData.sortOrder', 
                            direction: 'desc' 
                          })
    }
  }
}

Duplicate routes

More than one schema can claim the same route. When that happens, Enterspeed keeps all the views but serves only one of them. A route is duplicated when several views resolve to the same URL within an environment, or when several views use the same handle. URLs are compared after they are normalised - the scheme, query string and fragment are removed, the casing is lowered, and a trailing slash is trimmed - so https://example.com/Products/ and https://example.com/products are the same route. Nothing fails when this happens. The Delivery API returns one view, the remaining views stay in your tenant but cannot be reached, and no error is raised. This is why a duplicate route usually shows up as “the wrong view is returned” or “my view is not updating” rather than as an error.

Which view is returned

When several views claim the same route, the view that was processed most recently is the one returned. Do not use this as a way to choose which view wins. Because it follows processing order, the view that is returned can change whenever the content behind any of the colliding views is processed again - the Delivery API starts returning something different without you having changed anything.

Finding duplicate routes

The Tenant health tile on the dashboard lists the duplicate routes across your environments, worst first, together with the schemas that claim each one. The schema whose view the Delivery API returns today is marked (returned). Check it before you decide which schema keeps the route, so that resolving the duplicate does not quietly change what your application receives. Open a route in the route inspector to see every view behind it. Duplicate routes are detected as routes are written, not when you open the tile. A new collision appears once the colliding content is next processed, and one you have resolved disappears on the following refresh rather than immediately.

Resolving a duplicate route

Decide which schema owns the route, then stop the others from claiming it:

Narrow the triggers so only one schema runs for the source entity type.
Map the URL or handle so each view gets a route of its own - add the culture, the source group, or another distinguishing value.
Remove the route from the schema that should not be addressable on its own, and reference its view from the owning schema instead.

Deploy the schemas afterwards so the affected content is processed again.

Overview

Schema reference

API

Integrations

Tutorials

Best practices

CLI

MCP server

URL

Handle

Duplicate routes

Which view is returned

Finding duplicate routes

Resolving a duplicate route

​URL

​Handle

​Duplicate routes

​Which view is returned

​Finding duplicate routes

​Resolving a duplicate route

URL

Handle

Duplicate routes

Which view is returned

Finding duplicate routes

Resolving a duplicate route