Headless, API-first, wtf? A short introduction to all the Content Management System types


I have been blogging for all my online life now which reaches back to the very early 2000s. This is a very long time and it resumes all the technical background content management systems (cms) and blogging in general went through. I started with plain HTML, used all the famous blogging platforms (blogger, blogspot, livejournal, pitas, twoday, probably more..) and later found my home at (a self-hosted version of) the cms Wordpress like many others. My blog at rike.dev has been running quite a while on Wordpress.

But with all the modern JavaScript tech stacks, serverless deployments and the evolution of noSQL databases Wordpress (and its colleagues like Drupal, Typo3, and others) felt more and more unintuitive. I'm a JavaScript developer at heart so I more and more wanted to leave the PHP and MySQL stack altogether and stay flexible in which frontend technologies I use (React atm). Also, Wordpress feels bloated and overloaded especially if it is used for small blogs like mine.

For quite some time Wordpress seemed like the only popular solution for content-driven webpages, but in the last years some new paradigms in content management evolved that basically try to level up content management into the new web app age. I gathered some really short information about general cms concepts:

Traditional cms (= Coupled cms = Monolith cms = Regular cms)

This is what most non-technical people and content managers love: Traditional cms provide a monolith consisting of a backend and a tightly connected frontend that both work on the same database. The backend comes with a GUI and often with a WYSIWYG editor so that there will be no need to write code. Traditional cms like Wordpress come with a big set of addons, plugins, themes and - which is great - a very devoted community. They can be maintained by non-technical persons up to some point, though their configurations can get messy and complex.

Decoupled (= Hybrid Headless cms = Hybrid cms)

Decoupled cms crash the tight connection between the frontend and backend typical for traditional cms. The new approach is: The frontend consumes data from the backend via API, so it will never perform direct database operations. Decoupled cms also assist with a tool box including optional templates just like traditional cms enabling also non-technical people to publish their content and push it to various channels. A popular use case for decoupled cms are web shops.

Headless cms (= API-first cms)

They are defined as asubset of decoupled cms and go one step further: Chopping off the head of a traditional cms completely leaves a cms without a coupled frontend component: This means that the content will be provided in a raw data format, like JSON. This type of cms simply doesn't care about the devices and services that will consume the data created by the backend GUI. A popular buzz word connected to this paradigm is Content as a Service (CaaS), which puts the headless cms up into the cloud, providing a chargeable service to its customers, maybe you have heart of Contentful, or other services.

Flat-File cms

Most (self-hosted) decoupled and headless cms still rely on databases, e.g. MySQL, PostgreSQL or MongoDB. For complex projects this might be a practical approach, but for smaller websites or blogs a flat-file cms could suffice:  it does not require a database but rather, saves it's data to a set of text files, often XML files.

So which paradigm to choose for my blog?

At first I thought about using the (quite new) Wordpress REST API, but that would have meant to stay with the PHP/MySQL stack. What I definitively wanted was a flat-file cms without any database connection, just to keep it simple. Unfortunately, many flat-file cms still rely on PHP. Also out of simplicity decoupled cms were no alternative, so I searched for an API-first alternative and almost fount what I needed with Open Source projects like e.g. Strapi. But those still felt bloated and like an overkill to my use case, and I didn't like the thought of caring for another microservice on my server.

Just for fun I build my own super simple cms: It provides just one content type ("posts") so its use case would be blogs, mostly. It persists all posts into a simple JSON file without any database setup which makes it easy to backup as well. It has got a basic auth mechanism with only one admin user and of course provides its data via REST API. Like that the posts can be embedded simply anywhere - that's where your frontend skills are needed, no matter if you are a React, Angular or even Android developer. You can check it our on my Github repository.

For my own blog, however, I finally decided for a cloud-based Headless cms, which works very well for me.

In the end, it's up to you use case which cms to choose!