4 Critical Capabilities of Headless CMS API You Need to Integrate with External Systems

Integrating a new content management system (CMS) into your existing ecosystem of tools and services may be challenging, but not with a headless CMS with a quality API. Read on to learn how headless CMS API can help you prepare for the future.

There is no doubt that in order to connect content-as-a-service with its headless API-first approach to other best-of-breed microservices you have to have a good quality API on both ends, so that the services communicate and integrate well.

But what does a good quality API really mean? Of course, there are many different angles you can consider (e.g. it has to be testable, well documented, with solid error reporting, secure…). In this article I am focusing on the quality of a headless CMS API, and more specifically the required API capabilities you’ll need to be able to face typical challenges, while integrating a headless CMS into your existing ecosystem of apps or when building a new app or a website.

Why should you consider these capabilities? Imagine you select a headless CMS without critical API capabilities. Although you might not necessarily need these right now, what about in the future? How would you tackle this challenge? What if there is no workaround and you need to switch the platform? Save time, money, and more by thinking ahead!

Now, let’s have a look at the critical capabilities of headless CMS API:

1) API for Content Delivery

This is the most crucial part of an API of every headless CMS, as it allows you to retrieve stored content and deliver it into multiple channels (website, mobile app, IoT, and others).

There are several aspects of this API you should consider based on your needs:

• Probably the most important one is API service performance and availability. Fortunately, this is typically solved for you by the headless CMS that uses CDN (e.g. Fastly), which makes the content quickly available from wherever you are due to distributed data centers and a sophisticated content caching mechanism.
• To prevent others from getting your content, headless CMS provides certain API security features. For example, there may be a required API key with each request and additional configuration of content authorization in your app.
• Another aspect may be the availability of different SDKs and client libraries that makes retrieving content much easier. Most popular languages like Javascript, .NET, Java, PHP, and others are usually supported.
• For some developers it may be important to support GraphQL data queries and manipulation language, giving them the power to ask for exactly what they need in a single request, and more.
• In today’s multichannel world you have to be able to adjust content images to fit smaller screens and devices. The way it typically works is through image transformation on the fly via API (e.g. resizing, cropping, creating thumbnails).

2) API for Content Management

Although, headless CMS provides great tools for content editors to create and manage content, you as a developer will certainly get into situations where you will need to do it from your code:

• Typically you will need to import content from an existing content repository**.** For example, importing existing articles from an existing CMS into a new headless CMS. This usually means writing a script or an application that parses the content from its original format (be it a database from another CMS, or an XML, CSV, or text file) into a more general format (e.g. JSON) and sends it to a headless CMS via content management API. There is no doubt that importing content assets and other linked content (content that references to other pieces of imported content) is quite common, so make sure that the content management API of your headless CMS supports it as well.
• If you are leveraging a continuous development approach, you will need to make sure that all of your environments are in sync. Besides reflecting all created, updated or deleted content, you may need to reflect all changes of content types (e.g. to add a new content type attribute) and content taxonomy (e.g. to create a new content category) as well. And, this is where a quality content management API comes in handy.

3) API for Content Change Notifications

In the world of headless CMS and microservices it is very important to be able communicate with other applications and services. When it comes to headless CMS you will typically need to notify your other application or service when content changes to allow the application respond accordingly.

For example, if you are using a search-as-a-service (e.g. Algolia) to provide a full text search experience for your online articles, you will need to update the search index of your articles every time a new article gets published. The reason is that search index is stored and search capabilities are provided by that search service, i.e. outside of a headless CMS.

This notification mechanism of a headless CMS is usually ensured by webhooks. As stated above, think of webhooks as programmatic notifications that let your application know when something changes inside your headless CMS project — structured information about the type of change and the affected content are usually attached.

Similarly to other types of API, flexibility of webhooks is also important. For example,the ability to be notified not only when content gets published, but also when content gets moved to another step within the content management workflow (e.g. to notify a translation service about content to be ready for translation before publishing it).

Here’s some examples of how webhooks can be used:

• Notifying your team by sending an email, posting a message to a Slack channel,or moving a card inside Trello.
• Scheduling a social media post on Twitter featuring a newly published content item.
• Integrating with Zapier, IFTTT or other Integration platforms as a service (iPaaS) solutions that can help you integrate online services and applications, and automate tasks between them.
• Invalidating the cache of your app to make sure users see the latest content.
• Translating published content by creating its new language variant.

4) API for System Extensibility

There is no doubt that many content editors will need to use existing external content within the content they are producing in a headless CMS.

For example, you may need to use images from a Digital Asset Management (DAM) system for your articles. You can copy and paste the image URL, which is not very user friendly and hard to maintain. Or, a better option would be to let content editors search and pick the image from a DAM system within a headless CMS UI directly, and store just a reference to the image (some unique identifier) that does not change over time.

Another example would be leveraging external taxonomy by integrating with an AI tagging service providing automated tagging by extracting keywords and other information from assets uploaded into a headless CMS.

For these purposes, a headless CMS usually provides a certain type of UI extensions framework allowing you to integrate with external systems and use their content with the content in a headless CMS. At the same time it usually helps developers to a customize content authoring experience within a headless CMS to fit content editors needs (e.g. you can create a Youtube video selector or specialized Markdown editor).

Putting It All Together

Now you should have a better idea of the key capabilities of a headless CMS API to be able to build complex integrations, including:

1. Content delivery
2. Content management
3. Content change notifications
4. System extensibility

I am sure you have some more aspects that you may find important to consider for quality headless CMS API -please don’t hesitate to share them in the comments below. Looking forward to your inputs!

About the Author

Petr Vozak is the Technology Partnership Product Owner at Kentico. He works with technology partners to enrich Kentico Cloud and bring greater value to those using it.