blog Integrations

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

By Petr Vozak Dec 11, 2018

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 a 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? There are many different angles you can consider. It has to be testable, secure, well documented, and have solid error reporting. Let's look at the required API capabilities you'll need to be able to face typical challenges when integrating a headless CMS into your existing ecosystem of apps or when building a new app or website.

Critical Capabilities of a Headless CMS API

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!

1) API for Content Delivery

This is the most crucial part of the API of every headless CMS, as it allows you to retrieve stored content and deliver it to multiple channels including websites, mobile apps, IoT, and others. 

There are several aspects of this API you should consider:

  • Probably the most important one is the API service performance and availability. Fortunately, this is typically solved for you by the headless CMS that uses a CDN, such as Fastly, which makes 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, the 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. Usually, most popular languages like JavaScript, .NET, Java, PHP, and others are supported.
  • For some developers it may be important to support the GraphQL data query 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 the API, which covers resizing, cropping, and creating thumbnails.

Learn more about how Kentico Cloud handles content delivery.

2) API for Content Management 

Although a 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 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, whether it is a database from another CMS, XML, CSV, or text file, into a more general format, such as JSON, and sends it to the headless CMS via the content management API. There is no doubt that importing content assets and other linked content, such as content that references other pieces of imported content, is quite common, so make sure that the content management API of the 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 to content types (e.g., a new content type attribute added) and content taxonomy (e.g., a new content category created) as well. This is where a quality content management API comes in handy. 

Learn more about how Kentico Cloud handles content import. Check out the Kentico Cloud Product Roadmap for updates on our upcoming feature that lets you manage content models and taxonomy with a Content Management API

3) API for Content Change Notifications

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

For example, if you are using a search-as-a-service, such as 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, as the search service stores its index outside of the headless CMS.

The notification mechanism of the 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 the headless CMS project. A webhook contains structured information about the type of change and the affected content. 

Similarly to other types of API, flexibility of webhooks is also important. The ability to be notified not only when content gets published, but also when content is moved to another step within the content management workflow is super helpful. Webhooks can be used to notify a translation service about content that is ready for translation before publishing it. 

Webhooks can also be used for:

  • 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.

Learn more about Kentico Cloud webhooks support. Check out the Kentico Cloud Product Roadmap for updates on a feature we are considering that extends webhooks support as a part of Better Support for Automated Translations.

4) API for System Extensibility

Many content editors will need to use existing external content within the content they are producing in the headless CMS. For example, you may need to use images from a Digital Asset Management (DAM) system for your articles. In a less featured headless CMS, you can copy and paste the image URL, but that is not very user-friendly and can be hard to maintain. A better option would be to let content editors search and pick the image from a DAM system within the headless CMS directly, and store just a reference to the image through a unique identifier that does not change over time.

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

For these purposes, the 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 the headless CMS. At the same time it usually helps developers to customize the content authoring experience within the headless CMS to fit content editors' needs. For example, you can create a YouTube video selector or specialized Markdown editor.

Putting It All Together

Now you should have a better idea of the critical 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, so please don't hesitate to share them in the comments below.

Looking forward to your inputs! 

Subscribe to Kentico Kontent Newsletter

Stay in the loop. Get the hottest updates while they're fresh!

Hello.

We are Kentico.