Area: Optimizely Content Delivery API
Applies to versions: 2.3.0 and higher

Using friendly URLs

Recommended reading 

From version 2.3.0, you can retrieve content using friendly URLs. In addition to using the endpoint as in previous versions: http://localhost:8080/api/episerver/v2.0/content/6, you can use a friendly name URL of a specific content item for data query: http://localhost:8080/en/alloy-plan/. To use this friendly name URL to retrieve data, set the Accept header to 'application/json' in your request.

You can apply this rule for acquiring “children” and “ancestors” of the content item. You can use http://localhost:8080/en/alloy-plan/children or http://localhost:8080/en/alloy-plan/ancestors.   

The parameters for the request (for example, expand) should be the same as before. 

The following image shows the flow.


Content Language

The language to get content is extracted from the URL. If it is empty, then accept-language header is chosen.


  1. Make a request to http://localhost:8080/en with accept-language header sv. The language en is present in the URL, so it is chosen.
  2. Make a request to http://localhost:8080/ with accept-language header sv. The language is not present in the URL, so the language in accept header is chosen, that is, sv in this case.

Note: If the call to the Content Delivery API does not set the accept-language header (that is, the accept-language header is empty), as is the normal behavior of web browsers such as Chrome, it can automatically assign the value of the preferred language to accept-language (for example, en-US). The API will then use this value to query data.


Note the following restrictions:

  • You can use simple address to query content data, but you cannot use it to retrieve a content item's ancestors or children. For example, assume that the simple address of Alloy-Plan is http://localhost:8080/alloyplan. In this scenario, you can use the URL to retrieve Alloy-Plan data, but querying its children/ancestors by http://localhost:8080/alloyplan/children (or ancestors) does not work. 
  • A partial router is used for this feature and the type for both incoming and outgoing routing is IContent

    This can disrupt other partial routers in the site because the request URL is rewritten. To solve this problem, follow these steps:

    1. Create a new class (for example, CustomContentApiRouteService) that inherits ContentApiRouteService  and then, register a transient life-cycled implementation for a ContentApiRouteService in the initialization service.
    2. Override the ShouldRouteRequest function to prevent the URL from being re-written in unexpected cases. For example, requests whose accept types contain application/json are currently handled by the partial router. So, you can add one more header (such as Routed-By-ContentApi) for CD-related requests and then, use this header in the function to decide whether the partial router should handle the request and rewrite URL later on.
Do you find this information helpful? Please log in to provide feedback.

Last updated: Mar 11, 2019

Recommended reading