What is a headless CMS?

Knut Melvær is Head of Developer Relations, Sanity.io

You may have noticed already, there’s a shift in the content management systems space. Established CMS vendors have begun throwing around terms like “decoupled” and “APIs." New glossy CMSes that call themselves “headless” have begun to pop up. You may even have been told that you probably need one of these “headless CMSes,” because your content should not be tied to a single website anymore. So, what do you need to consider if you want to use one?

Before we headlessly dive into the world of content management, let me get this disclaimer out of the way: I work as a developer advocate for Sanity.io, a “software as a service” (SaaS) startup that offers a way to edit, manage, and use structured content. I will draw on past lives as an academic in the humanities, and as a technology consultant to keep this article general and useful, and not a sales pitch for our solution, or any other. This article is also edited to make sure I’m kept in reigns.

What is a “headless CMS”?

In this context “headless” is not used to refer to the late French aristocracy. The term is borrowed from a computer terminology for programs that don’t have a graphical user interface (GUI). In other words, a headless CMS is a content management system that doesn’t come with an out-of-the-box way to render content in a web browser. Instead, it makes the content available through APIs. Which begs the question, what is an API, and why do you want it?

If you’re not a developer, or do not see yourself as very technical, it’s something you should know about. It has implications for what you can expect to do with your CMS, and how easy it is for the programmers on your team to work with the content.

It’s all about the APIs

An API, short for “application programming interface," is what makes it possible for developers to write code that reads, updates, and interacts with your content. In practice, an application is given access to a URL on the web (often called “an endpoint”), which returns a structured list of content, which should be easy for a developer to integrate into their code.

There are different conventions for how to engineer and structure an API for a headless CMS. The most popular ones are so-called RESTful APIs and GraphQL. CMSes with RESTful APIs typically give the developer a selection of URLs (endpoints) returning machine-readable lists of your content. There’s nothing internally wrong with RESTful APIs, but they tend to be tedious to work with if you have some complexity in your data model.

You should know about GraphQL

GraphQL makes it easier for developers to both define and interact with an API more efficiently. This is why there is buzz around it. Whereas RESTful is like a set menu, GraphQL lets you order a la carte. So GraphQL support is something you probably want from a CMS.

(Note: There are other types of APIs, some of them even more powerful than RESTful or GraphQL. But these two are the most common.)

APIs, not just for reading

Headless CMS vendors usually put emphasis on the APIs for getting content from the system. However, you should also consider the API capabilities for getting content into the system. Many headless CMSes offer a web-based graphical interface for both building content models and editing content. But you may want to let other systems in your organization, or third-party services to be able to add, annotate, and to augment content as well. For example, you may have a catalog of always up-to-date product information, which you want to sync and embed in your marketing copy.

Other CMSes have APIs too!

Of course, vendors of traditional CMSes have registered the popularity of headless, and are beginning to offer APIs too. Their value proposition is that you get all that you’re used to, and everything that’s exciting with headless CMSes too. What they don’t tell you, however, is that you’re still pretty much tied to all the assumptions about the web presentation they have designed into their systems. So make sure to ask these CMS companies what capabilities they have when it comes to the flexibility you get for content types and the portability of your content.

Why would you want a headless CMS?

If the only thing you need for the foreseeable future is a way to manage content that ends up on one website, you can probably go with any traditional CMS that makes you happy. The real value of a CMS that’s built for dealing with content through APIs is when you want your content to be structured for many ways of presenting it.


A headless CMS is for when you want to

  • Reuse content across multiple channels

  • Tailor workflows to fit how your organization actually works

  • Be free to choose whatever tool you want to build services and presentations that use your content in any way or form

It also prepares you for a redesign and enables you to experiment and prototype with real content, without having to copy and paste or duplicate it.

Better content modeling

With a headless CMS, you get a way to structure your content that is not framed or limited by website concepts such as “a page” or even the site menu. Instead, you make a content model that fits some internal structure in your organization or company. For example, you make documents for types like “products," “people," “services," “events," “parts," or “documentation article." Then the layout, look, and feel of the interface can change without changing the underlying content.

Efficiency and cross-disciplinary work

Arguably, the most important thing you should measure a CMS by is how easily and efficiently it lets you work, iterate, and apply your content models. Traditionally, CMSes have required technical work and many hours from the vendor or an IT department to set up. Because most headless CMSes are in the SaaS category, they are mostly easy to set up and get started with. That means that you can start working with content early and have better, more informed conversations between the different disciplines on your team.

What you need to consider if you want to make the switch

What’s great with most headless CMSes is that you can start small, and move gradually. For most of us, this is a sensible approach, because switching from a traditional CMS to a headless one requires you to fundamentally think differently about how to structure your content and how to publish it. As a project manager, you should pick up the book Designing Connected Content by Carrie Hane & Mike Atherton*, which will give you great practical advice and strategies for the content modeling part. Designers, editors, and developers should come together to talk about the content model and where to put flexibility and rigidity in the content types.

From monoliths to distributed systems

Switching to a headless CMS is also an opportunity to rethink how many bells and whistles you actually want in your CMS. We now have a plethora of great, affordable SaaS products that are focused on doing a few tasks really well, and most of them have APIs that let you connect these services. While it has become way easier to integrate different systems, you should be circumspect and systematic in choosing services, since you have to make sure the integrations keep working.


The biggest change for many authors when first using a headless CMS is the loss of predictable layout contexts. Arguably, most of us should be used to this pattern already from the way we have begun to design websites. Text and images aren't displayed only as a single web page anymore – much of your content ends up in a preview box on Google or Facebook. That being said, it’s possible to build previews for the different contexts where some content is presented – some headless CMSes can even do it in real-time.

A perfect companion for structured content

It’s perfectly possible to work with structured content in traditional CMSes (Hane & Atherton use Drupal as an example in their book). Most headless CMSes are designed for that purpose, which is why they may prove a better fit. In my experience, they also align better with how developers and designers have begun working with digital products and services. Headless CMSes let developers and designers choose the tools they want to use for the job. They also take a lot of technical complexity out of the environment where authors work with content.  

More than ever, there are choices in what kind of tool you use to manage your content. Knowing the differences between them will help you make an informed decision.

* Note: There was no solicitation by Carrie for Knut to mention the book. His reading it was what made the connection and ultimately led to this post.