Too afraid to ask: What's an API? And what do APIs have to do with headless CMS?

We all know the situation: when you can’t hear what someone’s saying, but after three “sorry, what was that?” attempts, you end up cutting your losses and respond with a hesitant “Oh… yeah!”. 

Perhaps you’ve already experienced this with APIs. The term gets tossed around on a group meeting, so you ask what they are and maybe even ask a second time, but soon follows the slow “I get it, but I don’t get it” head nod.  

Or maybe you haven’t asked about APIs at all – that’s totally fine, too.  
Either way, there’s no denying it: headless is hot right now. So, let’s chat about APIs and microservices, what they are, and what in the world they have to do with headless CMS. 

What’s an API?  

The tech industry loves its three-letter acronyms, so let’s start there. API stands for Application Programming Interface. An API is simply the middleman that allows two different software systems to interact with each other. So, how do APIs work? 

A good API design gets data and functionality from one place to another without exposing you to the complexity behind the curtain. They’re facilitators, request takers, deliverers, messengers – they’re responsible for the hyper-connected world we’ve come to know and expect.   

The restaurant analogy is a classic explanation of API use wherein you (you = the user) look at a thoughtfully designed and formatted menu (menu = the front-end interface of software system #1, like a mobile app or a website).   

You tell the waiter (waiter = service API) what you’d like to order (order = data), but the waiter doesn’t know how to cook your meal, how to operate the kitchen appliances, or how to manage backstock ingredients. They simply give instructions to the kitchen (kitchen = the backend of software system #2), where your order is then prepared, passed to the waiter, and delivered to you just as requested.   

That’s an API: a convenient waiter waiting to take your request so they can optimize and deliver everything just how you like it, without you having to lift a finger.    

What are some real-life examples of APIs?   

APIs play an essential role in the automation of everything from mobile apps to e-commerce sites, and you probably interact with public APIs much more often than you think. If you’ve booked a trip online, ordered food on a delivery app, or called a rideshare at any time in your life, you’ve used an open API. And if you checked your weather app this morning… you guessed it, you used an API.   

In all of these instances, the information you’re looking for lives somewhere else. But because your API is a loyal messenger, it starts to exchange data. On your behalf, it asks a third party about flight prices, hotel availability, menu items, driver locations, weather forecasts and then reports back – all so you didn’t have to. 

Ok… so what do APIs have to do with headless CMS?  

Unlike a traditional CMS – sometimes called a monolithic CMS, like WordPress – a headless CMS separates the backend (where the content is stored and managed) from the frontend (everything you see and interact with, like this article you’re reading right now). Here’s a great overview of coupled vs. decoupled vs. headless.  

Because the frontend (head) is chopped off from the backend (body), headless content management systems use an API-first approach, relying on those little messengers to deliver anything in your content repository to different front-end channels and devices like webpages, mobile apps, web browsers, and social media platforms. 

Basically, no APIs = no headless CMS  

I’ve heard about RESTful APIs, what are those?  

We know that an application programming interface is how one software system talks to another, so now REST (short for Representational State Transfer) is a set of standard rules that programmers follow to build an API. And if an API is built to adhere to those REST rules, that API is what we call a RESTful API. There are other standard rules and types of APIs like web API, but REST is the most popular.   

This standard makes sure that your API speaks the same language as the application it's trying to communicate with operating systems, and RESTful APIs are necessary to keep that application active. RESTful APIs use a standard set of requests (get, put, post, patch, delete) to retrieve and manipulate data.   

Note: there's a lot more to the RESTful API story, but we'd ideally need a full programming crash course to encompass the entire picture.