Headless CMS Pitfalls

Back in the day, a content management system was a monolith that delivered the entire website. In the course of the increasing popularity of microservice architectures, Headless CMS came onto the market and transferred this architecture pattern to the content management area. 

However, it is the same as with any architectural decision: you have to live with trade-offs that are not found in product marketing. Therefore I would like to share my learnings from two headless CMS projects to consider early in your project.

What is a Headless CMS?

From a technical point of view, a headless CMS is a database for content and assets that can be managed via an editorial interface. Publishing frontends consume the entered content via APIs.

Implementation Complexity

CMS were originally introduced to reduce dependencies on software developers. With a headless CMS, however, the dependency on software developers increases again. You can query content via an API like GraphQL or REST. In addition, you can use any frontend framework to present the content. And this is where the complexity begins. In order to successfully introduce a headless CMS, a full stack development team is required to be able to consume those APIs, process the response and then render it on the (to be implemented) frontend.

Technical complexity often correlates with the degree of editorial flexibility. This is particularly true if you want to allow editors in a headless CMS setup to influence the hierarchy of the published pages and the arrangement of the components used on them. The more extensive the website is, the higher the chances that the editorial team would like to influence these two points. As a result, the headless CMS becomes more than a simple content repository and the scope to introduce such a setup increases.

Architecture Decisions

The flexibility of a headless CMS creates additional complexity in the overall software architecture. So before you start with a headless CMS project, you have to make some fundamental architectural decisions. 

For example how you want to handle the response of the CMS API. Either you query the CMS content directly from the frontend framework and also process the response directly. Or you introduce a caching layer in between. This creates additional complexity but reduces the dependency to the SaaS CMS provider. If there are availability problems of the external content APIs, it will in the worst case have a negative impact on the availability of your website or app.

In general, with a headless CMS you introduce content microservices that need to be managed and monitored. If you introduce a headless CMS with a big bang relaunch approach, there is the risk, that losses in scalability and performance need to be corrected at a later point in time. It is advisable to start with a very small MVP, fetch only a few content fragments and render them on your frontend. After a successful pilot in low-traffic areas of you website, you should add further areas to be delivered from the headless CMS.

Hardly Any Extensions

Headless CMS hardly offer any extensions as you know them from the classic CMS products. Classic CMS offer e.g. things like article recommendations or SEO extensions as plugins. However, since the primary use case of a headless CMS is offering a content repository, it is very likely that you have to invest in functionalities that monolithic systems offer via plugins.

Editorial Limitations

Another limitation to be aware of is the reduced functionality from an editorial perspective. Especially if the editorial team is used to a classic monolithic CMS that also delivers the web frontend, the team will have to familiarize themselves with new editorial workflows.

Headless CMS focus on the most necessary editorial functionalities in the authoring backend. Since frontend and content are decoupled, there is for example no such thing as a WYSIWYG editor in a headless CMS. 

One of the biggest limitations is directly related to this: the preview functionality. Since the presentation layer and the management of the editorial content are separate from one another, it is only possible with additional development effort and complexity to offer a preview of the page to be published. With classic monolithic CMS this is usually possible out of the box.

Monitoring

The reasons for monitoring the APIs of a headless CMS are basically the same as for monitoring technical systems in general: all systems fail at some point. You can only react accordingly if you know that the system is not available. In addition, it is important to know the performance of the APIs to be able to react to response time variabilities.

And last but not least, monitoring is relevant for your service level agreements, which usually play a role in SaaS products. I would like to know whether the promised level of availability is actually being met by the provider.

One Size Does Not Fit All

In headless CMS product marketing, it is often advertised that content has to be maintained once and can then be distributed to a variety of clients. No matter if it is a HbbTV client, a native smartphone app or a smartwatch. This promise made by headless CMS providers is largely, but not fully fulfilled.

In theory, it’s correct. In practice, however, you will quickly notice that each client has its own content requirement: for example field limitations, specific metadata or image formats. As a result, a simple text input field for editorial content has to be maintained multiple times with different character limitations to meet the needs of each frontend client.

Organizational Considerations

The introduction of a headless CMS also raises organizational questions. Especially if the CMS is a central system for content delivery for many stakeholders, it should be considered to establish a (CMS) platform team. The goals of this team are to provide content APIs for other teams and to create the best possible authoring experience in cooperation with the editorial team.

Different Cost Structure

With the introduction of a headless CMS, the internal cost structure to operate the technical infrastructure will most likely change. If the website was previously delivered by a monolithic CMS, you could count on a relatively easy-to-understand cost structure. In the simplest case, you pay the CMS provider and that’s it.

With a headless CMS, you are confronted with a more fragmented cost structure. In addition to the actual CMS costs, the following items may arise: hosting costs for the separate front end, databases to store the CMS response, code repositories, and tools to monitor the microservice setup. Plus the operation of the new microservice architecture requires higher internal personnel expenses, which may have been included by the CMS provider in the past.

Summary

The headless CMS market is understandably booming, and there is a good chance that headless CMS products fit better into a microservices architecture than a cumbersome monolith ever could. Still, not everything shines as much as advertised by the CMS vendors. One should be aware that the additional complexity in the implementation and in the technology stack, in general, can only be handled by a software development team with a heterogeneous skill set in the area of ​​frontend and backend development.

If the development teams are equipped with the necessary full-stack skills and you are aware of the challenges described in the article, the chances are very good that you will gain from the advantages of a headless CMS after a short time. Editorial workflows are becoming leaner and development teams are no longer slowed down by a monolith. Generally speaking, a content management system is reduced to what it should actually be: a lean content repository without unnecessary business logic.