Loading...
Area: Optimizely Content Delivery API

Quick start

Recommended reading 

This topic is intended to give you a brief overview of the most important steps to get started with Content Delivery API. More in-depth information is found in the other topics in the Getting started section.

In this topic

Step 1: Installation

Optimizely Content Delivery API consists one main NuGet package, EPiServer.ContentDeliveryApi.Core, and a number of additional NuGet packages, allowing you as a developer to install only the functionality you need. The different packages are described in detail in Installing Content Delivery API, but in short, these are Content Delivery API packages:

Packages.png

Install the NuGet packages in your solution using the NuGet Package Manager in Visual Studio or via command line:

Install-Package EPiServer.ContentDeliveryApi

Step 2: Adding search

If you have added the EPiServer.ContentDeliveryApi.Search package, you need to install Optimizely Search & Navigation and also add a licence for that.

By installing both the CMS and the Search package, (HttpConfiguration)config.MapHttpAttributeRoutes() is called twice. To fix this, add the following to your <appSettings>:

<add key="episerver:contentdeliverysearch:maphttpattributeroutes" value="false" />

Note: If you are running the Service API, you may have to disable settings for the CMS package as well. See Default HttpConfiguration for more details.

Step 3: Setting access rights

For security reasons, the Content Delivery API is not publicly exposed by default. When you have installed the relavant NuGet packages, you need to give the ContentApiRead role Read access to the start page and, if the whole site is available to the API, all its children. You can do this in admin view under Set Access Rights

Warning You should not expose content that contains secure information, such as API keys.

Step 4: Configuring Content Delivery API options

Configure the API and make it public in an initalization module like this:

[InitializableModule]
[ModuleDependency(typeof(ServiceContainerInitialization), typeof(ContentApiCmsInitialization))]
public class ContentApiInitialization : IConfigurableModule
{
	public void ConfigureContainer(ServiceConfigurationContext context)
	{
		context.Services.AddTransient<RoutingEventHandler, CustomContentApiRoutingEventHandler>();
		

		// set minimumRoles to empty to allow anonymous calls (for visitors to view site in view mode)
		context.Services.Configure<ContentApiConfiguration>(config =>
		{
			config.Default()
				.SetMinimumRoles(string.Empty)
				.SetSiteDefinitionApiEnabled(true);
		});
	}
}

If you do not make the API public, client JavaScript cannot anonymously consume the API and you will be required to log in when requesting the API from a REST client.

Site 5: Accessing site definition API

The initialization module you created in the previous step also enables a special site definition API which is useful for debugging scenarios. The site definition API is accessed by:

https://www.mywebsite.com/api/site/?language=en

The site definition API returns data such as siteSettings, language selectors, and currencies. You can query the API for specific pages or blocks, like this:

http://www.mywebsite.com/api/episerver/v2.0/content/{contentID}/

The content, if it exists, is returned in JSON format, for example, like this:

{
	contentLink: {},
	name: "About us",
	language: {},
	existingLanguages: null,
	masterLanguage: {},
	contentType: [],
	parentLink: {}
}

Depending on your data and what you want to achieve, some customization might be needed.

Step 6: Serialization

When data is requested, Content Delivery API serializes the data, that is, IContent is turned into JSON, before it is returned to the client. Depending on your site and needs, you may want to customize this serialization. For more information, see Serialization.

Serialization.png

Step 7: Re-index Search & Navigation

If you are setting up a site from the beginning, this step is unnecessary; but for existing sites with existing content, you should run the EPiServer Find Content Indexing Job in admin view to make sure your content is properly re-indexed.

Step 8: Testing and verifying the API

At this point, you should have these endpoints available on your host site:

# POST/GET Endpoint Description
1 POST /api/episerver/auth/token Authorization (Note: Only accessible if you have installed the EPiServer.ContentDeliveryApi.OAuth NuGet package.)
2 GET /api/episerver/auth/token Authorization (Note: Only accessible if you have installed the EPiServer.ContentDeliveryApi.OAuth NuGet package.)
3 GET /api/episerver/auth/token Get new access token by using refresh token (Note: Only accessible if you have installed the EPiServer.ContentDeliveryApi.OAuth NuGet package.)
4 GET /api/episerver/v2.0/content Retrieve multiple content items
5 GET /api/episerver/v2.0/content/{referenceORguid} Retrieve content by content reference or content guid
6 GET /api/episerver/v2.0/content/{reference}/children Retrieve child content of a content reference
7 GET /api/episerver/v2.0/content/{reference}/ancestors Retrieve ancestor content for a content reference
8 GET /api/episerver/v2.0/site Retrieve a list of sites in the system and their associated properties

To verify that the API is working properly, open the Site Definition API in your browser:

http://<your-site-url>/api/episerver/v2.0/site/

You should now get a 200 OK response and see the site and its associated properties:

[
   {
      "name":"ContentDeliveryAPI",
      "id":"124a76ca-932c-4e0d-a6e0-ae82f1a11899",
      "contentRoots":{
         "contentAssetsRoot":{
            "id":4,
            "workId":0,
            "guidValue":"99d57529-61f2-47c0-80c0-f91eca6af1ac",
            "providerName":null,
            "url":null,
            "expanded":null
         },
         "globalAssetsRoot":{
            "id":3,
            "workId":0,
            "guidValue":"e56f85d0-e833-4e02-976a-2d11fe4d598c",
            "providerName":null,
            "url":null,
            "expanded":null
         },
         "rootPage":{
            "id":1,
            "workId":0,
            "guidValue":"43f936c9-9b23-4ea3-97b2-61c538ad07c9",
            "providerName":null,
            "url":null,
            "expanded":null
         },
         "wasteBasket":{
            "id":2,
            "workId":0,
            "guidValue":"2f40ba47-f4fc-47ae-a244-0b909d4cf988",
            "providerName":null,
            "url":null,
            "expanded":null
         },
         "startPage":{
            "id":5,
            "workId":0,
            "guidValue":"3c745ea7-390c-4878-a11b-9f4cb1204e6e",
            "providerName":null,
            "url":"/en/",
            "expanded":null
         }
      },
      "languages":[
         {
            "isMasterLanguage":true,
            "urlSegment":"en",
            "displayName":"English",
            "name":"en"
         },
         {
            "isMasterLanguage":false,
            "urlSegment":"sv",
            "displayName":"Swedish",
            "name":"sv"
         }
      ],
      "hosts":[
         {
            "name":"localhost:60238",
            "type":"Undefined",
            "language":null
         },
         {
            "name":"*",
            "type":"Undefined",
            "language":null
         }
      ]
   }
]

Using Postman

Postman is a free tool that can be used as an API client to send REST calls. With Postman, you can connect to APIs and simulate calls to endpoints and their responses without having to set up a backend server.

To test the Content Delivery API, you can use a tool such as Postman and send a request to one of the endpoints mentioned in the above section.

Note: You should disable MinimumRole and RequiredRole in Content Delivery API (see Map RequiredRole to group roles in Configuration) for easier testing with Postman; otherwise, you will need to install the OAuth package and send a bearer token along in the header to get the data.

Related information

Blog posts

Do you find this information helpful? Please log in to provide feedback.

Last updated: Mar 23, 2021

Recommended reading