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:
https://www.yourwebsite.com/api/episerver/v3.0/site/?language=en
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.
http://www.yourwebsite.com/api/episerver/v3.0/content/{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 https://github.com/episerver/Foundation-spa-react
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.
