NEWS · October 18th 2019

Headless CMS explained in 2 minutes

A headless CMS is a content management system that provides a way to author content, but instead of web page rendering, it provides the content as data over an API.

Knut Melvær

Knut runs developer relations and support at

It can be a bit daunting to maneuver in today’s world of Content Management Systems. CMSes have been around for a long time, most of them providing different ways of authoring and structuring content for a website. Let’s explore their differences.

Headless CMS vs Traditional CMS

What we call “traditional CMSes” is software that you either install and have to manage in your own or a managed server environment. We tend to call them “monolithic” because they pack all functionality, and assumptions for how you want to work, in one single system. These CMSes often provide a “What You See Is What You Get” (WYSIWYG) experience because they only have one context for presenting the content: a web page. This means that traditional CMSs are adding APIs to serve content through network requests and the JSON format. On the other side, the headless CMS's have emerged to exclusively serve content through APIs.

What is a Headless CMS?

A headless CMS is a content management system that provides a way to author content, but instead of web page rendering, it provides the content as data over an API.

In the last few years, we have seen the uptick of CMSes that try to be more agnostic, and thereby more flexible in their ways of making content available. These are usually called “Headless” or “API-first” CMSes. Some of them market themselves as “Content infrastructure,” “Content Hubs” or even “Content as a Service.” However, when you take a closer look, they all pretty much boil down to some database backend with a web-based user interface, where you access the content through an API.

As a response to the introduction of headless CMSes, some of the traditional CMS vendors have built APIs on top of their systems and market them as “decoupled.” Their value proposition is that you get both the website rendering capabilities, and the flexibility of headless. What they do not tell you, however, is that their APIs are heavily restricted by a content model built for a single website. Moreover, the editing experience is still closely tied to just one type of presentation. In our experience, customers often have to jump through hoops to get these APIs to play nicely with their additional digital products.

How does a Headless CMS work?

A headless CMS works by giving editors an interface for managing content while providing APIs for developers to build applications on top off. Most headless CMSes are offered as a Software as a Service, meaning that your editors will have to log into a web application and that the APIs are hosted in a cloud-based backend. Some headless CMSes will let you host the whole solution on your own server and database (requiring you to do your own scaling and operations). With Sanity you can host the customizable editor interface yourself while getting the advantages of the hosted real-time backend – no-ops and effortless scaling.

To better understand the value proposition of a headless CMS it’s necessary to know more about APIs. API stands for Application Programming Interface, which in this context means that you get content in a way that is easier to integrate with existing or new software solutions. Usually, you do this by sending the headless CMS a network request to an endpoint. This network request is pretty much the same thing you do when visiting a webpage, e.g.,, but instead of a web page, you get a list with the post’s contents back.

Developers can use this information when building software, be it an app, a voice interface, or a webpage. Most of today’s developers are used to programming with APIs and prefer them because it leaves them in control of how to build their systems. Some CMSes also allow changing content through APIs. API is a pretty generic term and goes beyond the world of CMSes and the World Wide Web. Therefore, it can be useful to zoom into the two most used types of APIs that when it comes to content management: REST and GraphQL.

Headless CMS Benefits

  • Respond faster to editor needs
  • Better workflows
  • Scale easier
  • Work faster with instant updates
  • Enhanced security

What is REST API? What is GraphQL?

It’s important to know that APIs can be more or less flexible or restrictive regarding how much effort it takes to make products on top of them. Traditionally, Headless CMSes have offered REST APIs that structure the content behind multiple URLs (e.g., /posts /authors /images and so on), where you have to stitch multiple requests with the IDs of the different content types together. REST APIs can be great for simple data structures but tend to get tedious and time-consuming to use when your content models are more complex. It’s also a more laborious exercise to change or fit these APIs for different uses.

Facebook developed the API standard GraphQL as a response to the less flexible REST convention. GraphQL lets you query the API with the fields and relationships you need for each occasion, almost like what you can do directly with a database. It’s also easier to implement new fields and content types as your system matures. We have also seen a rise of developer tooling for GraphQL, for example from Apollo that makes it easier for developers to deal with user interaction in digital services.

Sanity stands out of the crowd because it offers the most powerful and flexible API of any of the CMSes. The simple query language called GROQ, created by Sanity, that lets you get exactly the content you need in any way or form you need it. Using GROQ significantly reduces development time and makes it easier to make decisions about the content model. You can make a document with an entirely new content model and have it instantly available in the API without any deployment or code changes.

The reason we care about good and flexible APIs is they can break the bottleneck that makes it hard to reuse content across channels. In other words, having good APIs on top of structured content makes it portable. But why is that a concern?

What is the value of portable content?

Now – and increasingly so going forward – organizations and businesses need to be available in multiple channels, be it different websites, apps, voice assistants, or even printed material. The multichannel presence puts a new demand on how content should be managed and delivered. Acquiring a headless CMS and having the content available through APIs is a good start. However, you also want that content structured in a way that makes it easy to use and adapt.

With this in mind, we find puzzling that nearly all modern headless CMSes choose to restrict their rich text models to how text presented on the web, namely by saving it in HyperText Markup Language (HTML). HTML is great when all you do is to deliver it directly to a web browser, but get cumbersome when you try to use it in a native app, or even in one of the popular JavaScript frameworks, like React or Vue. Parsing user-generated HTML can be difficult and unpredictable.

That’s why Sanity designed the Portable Text specification as the underlying model for how to store rich text. Authors still get a familiar editing experience, and developers get a predictable format that is easy to tailor where-ever one wish to display the text. It also allows us to have our rich text editor to be highly customizable. From letting users insert custom made content blocks inline, choose how the editor should insert copy-pasted content, and direct how the text should be visually presented.

Beyond customizability, it also allows for deeply typed content structures where relationships between content types are possible within and on top of rich text. Practically, it means that you can link to some internal document and have Sanity index it. It then prevents you from accidentally deleting other documents linked to that document and even lets you query those relationships.

Use cases for Headless CMS


A Headless Content Management System gives editors an interface for easily managing content, while providing APIs for developers to build applications, making it simpler and faster to store, edit and publish content.

Sanity: The fully customizable headless CMS

Whatever you choose to call it: Sanity’s core capabilities take it beyond the offerings of popular headless CMSes and the older monolithic CMSes on the market. We built Sanity for real-time workflows and full scalability from the ground up. Contrary to other hosted content-as-a-service vendors, we offer a fully open-sourced and standalone editor built in React, the world’s most popular JavaScript framework. This combination of features and capabilities makes Sanity a perfect fit for teams that needs a way to manage content alongside with legacy systems in-house, serverless AI content augmenting services, and digital products of any kind.

Build a Headless CMS in minutes

For the past year I've been obsessed with digging through and testing out different #headlessCMS for the #JAMStack comparing feature sets for editors, DX, extendibility, etc. Honestly by far I think @sanity_io stands WAY out and I can't believe how mature the product is! @kevinpmcaloon - Jun 18, 2019