Skip to main content


Optimizely Content Delivery API

Discussing Business Opportunities

Optimizely Content Delivery API

To build Optimizely pages and blocks on a website, we use C# MVC razor helpers in the Optimizely Content Management System (CMS). Now, we can utilize CMS in a headless manner using the Optimizely Content Delivery API, meaning that all pages and blocks are produced by reading JSON data returned from a REST API.

By retrieving the Optimizely page and content data over HTTP, you can create Optimizely sites such as Single Page Applications (SPA) sites, mobile apps, or other external applications without utilizing the Optimizely user interface. To create a SPA application, combine the Optimizely Content Delivery API with JavaScript frameworks like React, Vue, or Angular.

Optimizely CMS has a robust presentation layer, therefore it is not a headless CMS. However, there are instances when a headless approach is preferred to provide the ability to pull raw content from outside the presentation layer, in which case the Optimizely Content Delivery API can be used.

What is Content Delivery API?

Using the Content Delivery API, Optimizely makes its data accessible to developers. This allows users to access content such as JSON over a REST API and use Episerver as a Headless CMS.

The Content Delivery API is a pluggable and configurable web API for querying content, providing users the ability to:

  • Deliver content
  • Use Optimizely Search & Navigation to query content. (Optimizely Search & Navigation is installed via the EPiServer. The NuGet package requires a separate license.)
  • Support localized content and multi-site scenarios.
  • Leverage common querying, filtering, and sorting scenarios.
  • Support returning access-controlled and personalized content.

Important steps to get started with Optimizely Content Delivery API.

Install packages

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

dotnet add package EPiServer.ContentDeliveryApi.Cms

Add search

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

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

Configure Content Delivery API options

Next, configure the API in ConfigureServices in startup.cs:

services.AddContentDeliveryApi(options =>{    
                                          options.SiteDefinitionApiEnabled = true;

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

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 accessible by:

The site definition API returns data such as site settings, language selectors, and currencies. You can query the API for specific pages or blocks, displayed below.{contentID}/

If the content exists, it is returned in JSON format. For example:

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

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

Limitation of Content Delivery API

With the release of the Content Definition API, it is now possible to develop a fully headless solution with total separation between the front end and back end, while maintaining the content structures entirely in the front end.

To achieve strongly typed objects, you will still need extra development efforts, for example here

There is no alternative for some .Net attributes like AllowedTypes (e.g. to restrict ContentArea for specific blocks)

The Content Definitions API must be version 3.4.0 or later to support the Language Branch API.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Vaibhav Warhadpande

My name is Vaibhav Warhadpande, and I Work at Perficient as Senior Technical Architect on the following products/technologies: Optimizley CMS, Insite Commerce, Sitecore, ASP.Net E-commerce application, I am Sitecore certified developer and worked mostly on CMS and E-Commerce application development

More from this Author

Follow Us