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

Using friendly URLs

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, a friendly name URL of a specific content item can be used for data query: http://localhost:8080/en/alloy-plan/. To use this friendly name URL to retrieve data, you only need to set Accept header to 'application/json' in your request.

This rule can be applied 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 flow is illustrated by the image below.


Content Language

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


  1. A request to http://localhost:8080/en is made with accept-language header sv. The language en is present in the URL, so it is chosen.
  2. A request to http://localhost:8080/ is made 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, they 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:

  1.  Using simple address to query content data is fine, but it cannot be used to retrieve a content item's ancestors or children. For example, let's assume that the simple address of Alloy-Plan is http://localhost:8080/alloyplan. In this scenario, using the URL to retrieve Alloy-Plan data is fine, but querying its children/ancestors by http://localhost:8080/alloyplan/children (or ancestors) does not work. 
  2.  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:
    • Create a new class (for example, CustomContentApiRouteService) that inherits ContentApiRouteService  and then, register a transient lifecycled implementation for a ContentApiRouteService in the initialization service.
    • Override the function ShouldRouteRequest to prevent the URL from being re-written in unexpected cases. For example, requests whose accept types contain application/json are currently handled by our partial router. So, you can add one more header (for example, Routed-By-ContentApi) for CD-related requests and then, use this header in the function to decide whether our partial router should handle the request and rewrite URL later on. 

Last updated: Mar 11, 2019