In this tutorial, you will learn how to enable the content delivery API within Optimizely CMS 12. Contained within this guide, you will learn how to configure the API as well as learn some useful tips that will help you get it working up and running with minimal stress 😟
The content delivery API is the Optimizely approach of allowing content added within the CMS to be accessible via APIs. If you want to access CMS content from your mobile app, you want to create a complex API, or you are considering building a 'decoupled` (not headless) website using Optimizely CMS, the content delivery API is the thing you will need to master 🎓
Getting Content Delivery API up and running is fairly easy when you know the steps, however, I struggled with the lack of documentation. To make sure you do not have to experience the same pains that I did, I am sharing all my tips within this guide. If you want to be a content delivery master, this is the tutorial for you 🔥🔥🔥
Installing Content Delivery API
Installing Content Delivery API is done via NuGet. Make sure you have the Optimizely NuGet feed installed within your NuGet feed sources:
Find and add these packages:
Within .NET 5, we enable stuff within the Start.cs file. You will need to register content delivery API within ConfigureServices(IServiceCollection services) using this code:
At a basic level, this is all the code required to enable the content delivery API. It is also possible to further configure the content delivery API by passing in additional parameters. If you are an old pro with content delivery API, one word of caution is that some of the properties that used to exist and now obsolete, This means that you will not be able to configure the API using some of the properties you used to be able to use. You can learn more about what has been removed here.
In this guide, I will only focus on enabling a public content delivery API. If you want to restrict it, say for preview, you can find some useful code here to learn how to lock it down.
One thing that you will likely want to configure is CORS. The CORS policy will define what hosts can access the content via the content delivery API. One important thing to note when enabling CORS within Optimizely CMS is that you will likely need two policies. One for the API and another policy if you want your assets to be accessible as well. To make assets accessible you need to create a separate static file policy, so be wanted ✔️
When it comes to CORS we have a few ways to enable it within start. First, you can define CORS within ConfigureServices():
It is also possible to add CORS within Configure(), like this:
Use the approach that works for you and makes you happy❤️. If you want to access images, files and other media, you will also need to enable CORS on the static files. You can enable static files CORS within Configure(), like this:
Accessing the API
With content delivery API enabled, it is time to debug it. You can learn more about the different API calls here. For example you would query the API for data about your homepage using this Url:
My tip is to debug the content delivery API using Postman. You need to use Postman rather than a browser, otherwise, you will encounter a 404 error. The request needs to have the correct HTTP header for it to return data. The request needs to set Content-Type as application/json.
Another important thing to know about the API is the expand property. If you query the API for content that contains a content area, by default the blocks contained within these areas will not be returned. BY default you will only get the data returned for the object you are querying. In order to return more data you can use the expand property, like this:
With this flag enabled the API will return additional data that can be found within the expandedValue property.
Another important thing to note is that the API only returns 2-levels of data. If you query a page, that contains a content area, that contains a block, that contains a content area that contains blocks, these blocks will not be returned within the API call. To return this data, you either need to make an additional call, or, you need to write some custom code and customise how the API works. I won't cover how to do that here, however, be warned as it can be confusing!
Content Delivery API Javascript SDK
The great news with content delivery API 3 and Optimizely CMS 12 is that there is a new Javascript SDK that you can now use. If you are using React or Vue, I recommend you use this SDK to access data from the API rather than writing something custom yourself.
In the long run, using the API will save you a lot of time and reduce the amount of code you may need to maintain later on. You can learn more about this SDK from GitHub here 💥
You are now an Optimizely CMS Content Delivery API master 🎓🎓🎓. If you want to access CMS content via an API this is the thing to use. In the future, you might be able to use the GraphQL layer, for now, Content Delivery will meet your needs. Go forth and be HEADLESS. Happy Coding 🤘
