Quick start

Install packages

Optimizely Content Delivery API consists one main NuGet package, EPiServer.ContentDeliveryApi.Cms, and a number of additional NuGet packages, letting you install only the functionality you need. The packages are described in Installing Content Delivery API.

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

dotnet add package EPiServer.ContentDeliveryApi.Cms

Add search

If you added the EPiServer.ContentDeliveryApi.Search package, install Optimizely Search & Navigation and also add a licence for that. Configure the API in ConfigureServices in startup.cs:

services.AddContentSearchApi(options =>
{
    options.MaximumSearchResults = 10;
});

Set access rights

📘

Note

Content that has read access for the 'Everyone' role is available through the API by default. You can change this in the following ways:

• Configure AllowedScopes in ContentDeliverApiOptions. Then requests need to have any of these scopes to call the API.
• Configure RequiredRole in ContentDeliveryApiOptions. Then assign these roles read access to each content item that should be available in the API.

❗️

Warning

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

See Configuration and API authentication.

Configure Content Delivery API options

Configure the API in ConfigureServices in startup.cs:

services.AddContentDeliveryApi(options =>
{
    options.SiteDefinitionApiEnabled = 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.

Content Delivery API and HTTP Caching

You can control how long the API response is cached by adding the Cache-Control header to the response. Configure the cached time with HttpResponseExpireTime :

services.ConfigureContentApiOptions(o =>
{
	  o.HttpResponseExpireTime = TimeSpan.FromSeconds(1);
});

Access site definition API

In the previous step, you enabled a special site definition API, which is useful for debugging scenarios. The site definition API is accessed by:

https://www.mywebsite.com/api/episerver/v3.0/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/v3.0/content/{contentID}/

The content, if it exists, is returned in JSON format. For example:

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

Depending on your data and what you want to achieve, you may need added customizations.

Serialize the data

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.

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.

Test and verify the API

You should have the following endpoints available on your host site:

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

http://<your-site-url>/api/episerver/v3.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
         }
      ]
   }
]

Use Postman

Postman is a free tool that you can use 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.

See also: How To Enable Block Preview Inline Editing Using React And Episerver Headless blog post by Jon D. Jones.