Headless CMS explained in 2 minutes

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 and why Sanity sticks out of the crowd as a real-time hosted backend for structured content.

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” experience because they only have one context for presenting the content: a web page.

A headless CMS is a content managment 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.

To better understand the value proposition of a headless CMS it’s necessary to know some stuff about APIs. It’s a term that is more and more of use, but we can’t always assume that people have a good understanding of what an API is. Let’s take a closer look.

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., https://yourdomain.com/api/posts/, 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 for 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.

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 which 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 mature. 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. We designed a simple query language called GROQ 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.

Later this fall, we will launch an additional GraphQL API on top of Sanity, and offer our users the best of both worlds: The flexibility of GROQ and the ecosystem of GraphQL.

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?

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 which is easy to tailor where-ever one wish to display the text. It also allows us to have our rich text editor 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.

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.