Why everyone needs to understand the basics of APIs

You might know what APIs (Application Programming Interfaces) are. If not, you can imagine them as sockets and extension cords connecting different applications and services. 

So what’s important about connections? In order to connect two systems, be it applications or appliances, you need to have a common interface. Alternatively, you need some logic in place to convert interfaces between not matching connections. Once you have the same interface, or one allowing for conversions, you pretty much get limitless connection options.

Having options is great if you’d like to avoid vendor, technology, channel, or layout lock-in. 

Vendor lock-in

Vendor lock-in

To dissect it further, let’s look at vendor lock-in. The risk of vendor lock-in in the monolithic CMS world is high because of how everything is tied together. These vendors don’t necessarily have good APIs, as they provide everything in one black box, such as what content is displayed and how it looks. If you don’t like something about your monolithic CMS’s front end, you’re in bad luck. There might be APIs available, but usually, they are inadequate since vendors don’t have an incentive to improve them. On the other hand, headless vendors rely on APIs. Bad APIs mean accessing content is bad, thus making such a CMS bad by definition. 

Language lock-in

The other aspect of vendor lock-in is the data format question. In this article, I’m using English to transfer my thoughts to the screen and to you. This wouldn’t be possible if I were using my own proprietary language. Ideally, the language would be clear of any unnecessary formatting. Changing background colors a couple of times in one sentence wouldn’t help. Same with CMSs—the vendor should be using a common data format for communication without unnecessary, unimportant information. 

Technology lock-in

Technology lock-in is something to think about too. Limited APIs limit your outreach. The CMS you’ve selected might have amazing support for the web channel, but it falls short elsewhere. We could go even further and say some CMSs inhibit the use of content in other channels due to their clunky API. You won’t be able to get that one content item formatted well on a smartwatch if itʼs designed to fit only on phones or monitors. 

Channel, layout and technology lock-in

An API should give access to everything

A good API allows a seamless flow of your content model and by extension your content anywhere, into any front end. I’m saying content model, not only content because the CMS shouldn’t dictate which content is accessible. Content consumers are the ones who dictate this. You are only able to cater to their needs if the API is good enough to allow for that. One important distinction between a good and bad API is what it allows you to do. A good API allows for CRUD: Create, Read, Update, and Delete operations covering most, if not all, operations over your content model. Not only that, ideally, a good API covers all administration operations which you can perform in the CMS too. Such broad coverage allows for easy migrations, exports, and advanced integrations with other services. 

APIs shouldn't interpret

A good API reflects your content model. The API shouldn’t voluntarily interpret your content model because the model represents important semantic relationships. The API should be an enabler. It should enable the adaptation of your content model to push content anywhere there’s an internet connection. Be it smartwatches, voice interfaces, or billboards. 

API and the model stability and chunkiness

The tight connection between the content model and the API is important. Let this sink in. It means that the model needs to be extendable, sufficiently chunked, but stable. Identifying and creating reusable chunks allows the developers to access chunks, adapt them to fit any medium, and deliver them in a personalized view to your content consumers. This API chunkiness allows you to also easier identify high-value content, which is invaluable when deciding what to write about next. All this and more can be done with a capable API.

API chunkiness and content model chunkiness should be the same

An example

So what does all this mean? In the CMS space, this means supporting an easily adaptable data format, such as JSON (JavaScript Object Notation). Beware that some data formats, such as XML, already come with an embedded format or at least layout information. This might cause issues if you need to support different layouts on other channels. 

So JSON is your socket. For the cord, you need to have a universally adopted communication protocol, such as REST (Representational state transfer). So REST is your cord. The actual communication is enabled by a good API with abroad coverage of internal admin and external-facing CRUD content operations. A good API reflects your content model faithfully and allows you to identify content based on invisible semantic relationships. 

One last thing to cover are additional APIs that may come with a CMS. These capabilities might differ greatly, and they can give you great benefits as well. For example, there can be a way to extend the CMS seamlessly for editors. Imagine having a library of apps that will enhance the day-to-day tasks—instead of copy-pasting a YouTube link into a form, you can get a YouTube selector with preview. This already enhances the experience significantly, so make sure you check for any helpful APIs coming with the solution.

Getting into the world of APIs might sound daunting, and there is much more to explore. However, even these basics will make you better equipped to pick a CMS capable of creating a future-proof content model. 

Key Points

To sum up:

  • Understanding basic API terminology will help you to avoid vendor, coding language, and technology lock-in
  • APIs should follow your content model and give you access to all content.
  • Headless CMS APIs need to be stable and use industry-wide accepted formats.