Headless Drupal - What, When,How & Where -The Ultimate Guide To Decoupled Drupal

In a traditional Drupal website, Drupal is the end to end solution for serving users with pages. It is used to create, store and display content to the end-user. In a headless approach adding and storing are still done on Drupal but displaying is not.

Definition:

Headless Drupal is an approach to building Drupal websites, in which Drupal serves as the backend content repository. The frontend is built in different technologies and communicates with Drupal via an API. 

In the graph, we can see that Drupal serves as the backend system. The frontend, which the client sees, is separate from Drupal. That is where the headless name comes from - Drupal does not have the top layer anymore (the head ;), but only exposes the APIs which the frontend consumes and uses as content sources.

The frontend can be built in various frameworks and programming languages. Mostly, however, this will be one of the below:

• Javascript - vast majority of cases - frontends are mostly built on frameworks like React, Angular or Vue, which allow for quick creation of dynamic and interactive interfaces. If there is a requirement (eg for SEO purposes) to pre-render the pages on the server, Nextjs or Gatsby can help.
• PHP - sometimes the frontend is built on a fast PHP framework like Symfony or Laravel. This would be done mostly when pre-rendering on the server is required. An additional upside is that since Drupal is built on PHP and uses Symfony, often the same team is capable of handling the frontend.
• Any other - a website in any other technology which can talk to an API can consume content from Drupal. 

Why chose headless Drupal

There are many reasons why companies might choose to use a headless approach to Drupal. Below I will list the most common ones.

More consumers of content

These days brands communicate with their customers not only through their websites but via multiple channels. CMS, therefore, is not used only to send content to web browsers. It pushes content to various other places. You can read more about the changing marketing landscape in a post about Digital Experience Platforms.

Drupal is fantastically positioned to be the source of content for various consumers. Apart from serving content for a frontend website, decoupled Drupal can serve content via an API to be consumed by various other mediums, in which the brand wants to be present:

• mobile applications
• IoT
• kiosk displays
• etc.

Microsite manager

Sometimes a company needs to create multiple websites which are separate (eg. one for each brand, event, promotion, country), but which will share a lot of content. In such a case, it might be easier to create one content engine (Drupal) which will deliver content to all the microsites. The microsites can be quickly created and closed whenever a need arises and the content can be contained in one content hub.

Need for an elegant UI

Drupal is fantastic for content creation, data storage etc, but it is written in PHP which is a server-side rendering engine. It the particular website or app or website requires a very elaborate UI or simply is interactive it probably has to be built in javascript.

Javascript allows us to create fantastic interactions which are easy to use for visitors and are fast. Libraries like Angular, React or Vue help developers quickly create complicated frontend applications. Progressive Web Applications - a standard published by Google is also gaining momentum and it requires an application to be built in javascript.

If you want to build an interactive web application, marrying drupal with a frontend Javascript framework is a really great option. For a tutorial, you can check out our article about combining drupal and react.

Diversification of teams

Drupal experts are very hard to come by. Some companies, to move quicker, decide to build the backend in Drupal and hand frontend off to a team specialising in a different technology, in which talent is more available or which is simpler to learn.

Another benefit of inviting various teams to work on one project is sharing best practices from various sources. This may results in much better end results than relying on one team to build the backend and frontend.

Reducing technological dependency on one platform

The bigger the system one builds on Drupal, the greater the reliance on it. Abstracting Drupal from serving the frontend, allows companies to be more dynamic in changing the frontend technologies, without having to rebuild or re-architect huge Drupal backends.

Many websites, which have to maintain a fresh, modern look undergo a re-design every few years. If the frontend is separated from the backend it is much easier to rebuild. In such cases, the overall cost of the website might turn out to be lower than if the Drupal website was being rebuilt.

Drupal is great for headless

Drupal is very often chosen when a headless CMS is required. The reason for this is because Drupal out of the box has most of the required functionality. It is one of the most mature CMSes and has fantastic APIs.

Drupal community is working very heavily to allow Drupal to be a great API-driven CMS. In 2016 an “Api First”  initiative was launched. Its aim was to coordinate the development effort to allow Drupal to be a fully headless CMS.

As of writing this, enormous progress has been made in allowing Drupal to serve and receive content via APIs. 

RESTful module

Since Drupal 8.2 there is a RESTful module available in Drupal core which out of the box allows for easy interaction with all standard entities available in Drupal (nodes, users, taxonomies, comments). Accompanied by REST UI module it allows for very fine-grained control of what can be accessed via the REST API and how.

Initially, this module was the standard for building headless Drupal installations. It comes however with a few pain points, what sometimes makes it quite difficult to work with.

1. Returned data structures are by default derived from drupal arrays, which converted into JSON are not very user-friendly and difficult for frontend developers to navigate.
2. Getting and liftering lists of entities it a bit troublesome. For each type of list and filter, a view in Drupal with particular fields and exposed filters have to be created. Frontend developers cannot easily ask for custom lists

Despite the downsides, RESTful was a fantastic step in the right direction.

JSON:API module

JSON:API module was shipped with Drupal 8.8. It has massively improved the REST experience with Drupal, making it an incredibly versatile system far superior to practically any CMS on the market.

JSON:API module exposes all entities in Drupal allowing for easy interactions, but it does so in a very elegant fashion:

1. It is compliant with the JSON:API standard (https://jsonapi.org/) making it easy for anyone wanting to integrate with a Drupal website easy to understand the data structures without the need for a lot of custom documentation
2. It allows to query for lists and filter by entity properties  and fields also following the JSON:API standard

The core JSON:API functionality is further extended by JSON:API Extras module, which allows for additional configurability of the endpoints.

The above features effectively turn Drupal into a super robust backend for frontend applications, where all data structures can be created using the Drupal UI, whilst the REST endpoints are automatically working out of the box without a need for any programming work.

An in-depth comparison of the two modules can be found here: https://www.drupal.org/docs/8/modules/jsonapi/jsonapi-vs-cores-rest-module

REST in Drupal is baked deep into the system

What is worth mentioning is that in both of the above, modules the REST APIs are not added to Drupal as an afterthought. They are deeply baked into Drupal core. Drupal access control, preprocessing of values, hooks, events etc. All these are automatically taken into account when an access point is queried just as it were when a Drupal node was requested in a more traditional fashion by accessing a URL via the browser. 

This gives Drupal a massive edge over other CMSes. Using REST, you can still extend and alter default behaviour in any way you want!

Headless vs progressively decoupled

In this article, we are discussing headless Drupal, but it is also worth mentioning that it is not the only way to add interactivity to a Drupal website. Another option is to create a progressively (or partly decoupled) Drupal architecture.

Progressive decoupling is an approach closer to a typical Drupal setup, where the initial request to the server is managed by Drupal and the page send back is assembled by Drupal. On the page, however, we embed interactive elements build in javascript, which then fetches data it needs by calling a REST API also provided by Drupal. 

This approach might make sense in the following scenarios:

• Most of the website is not interactive but there are a few highly interactive elements which require Javascript.
• The website uses external data sources which should be presented to the user but do not come from Drupal and are not well suited for Drupal (eg. time changing stock quotes) which can be pulled directly from the source by a JS app embedded in Drupal

If you are not sure which solution to choose, there is a great post by Dries Buytaert on how to decouple Drupal in 2019.

Important considerations

Development is more complicated and more expensive

A Headless infrastructure is more complex than a traditional Drupal website. This can cause additional difficulties and can increase costs. Deciding on a headless, you should consider whether the benefits outweigh the costs. 

Managing multiple teams

In a headless Drupal, there are 2 separate components (frontend and backend) and these have to be developed (at least to some extent) in coordination. Quite often, there will be separate developers or teams (backend and frontend) working on the website. Sometimes these are 2 different companies. This requires coordination and much more communication because data models have to be agreed, endpoints created and tested. It is true that in Drupal many of these might be available out of the box, but most probably there will be requirements for some custom ones.

Higher overall development costs

Overall development time will probably be higher since we now build 2 systems, and therefore development cost will also be higher than that of a comparable standard Drupal website, especially taking into account the coordination effort.

Higher subsequent maintenance costs

Maintenance of a decoupled system is more difficult. Tests are more important when you rely on REST APIs because changes to one system might make it not compatible with the other.

Deployments might have to be more orchestrated where changes to multiple both systems are deployed all at once. Alternatively, multiple versions of an API might be maintained, but that also adds to the cost. All of this might increase maintenance costs.

Also, security releases will be required more often since there will be a need to patch not one but at least 2 systems.

SEO (and other metadata consuming engines)

Google becomes better and better in indexing javascript content but still, it is safer and much more effective to be able to provide it all the content on the first request to the main URL. If your website heavily relies on traffic from search engines, a decoupled approach might not be the best solution.

You should also take other services into account. For example for content to be nicely shareable via Facebook and Twitter, each piece of content has to have a separate URL and what is also important, must return the basic data obtainable without javascript. At least for now, Facebook and Twitter when you share a link there, prepare the preview by querying the link without enabling javascript. The title, image and description information should, therefore, be available without the need to enable javascript.

Solutions:

Shareability - returning metadata information on routes

For Facebook and Twitter, it is enough to return a small part of websites content on each route. This can be even done, and sometimes is, by a simple script in a server-side language (in PHP or python etc) which, depending on the route queried, returns different metadata. The server, instead of serving a flat HTML file with a js application, parses a script and returns identical HTML with just the meta tags varying.

SEO  - Server-side rendering

For SEO purposes the above approach can also be used, but typically another way is more efficient. Assembling a complete page with content often requires quite a lot of logic, which then has to also be available in the frontend application. Writing the same page assembling logic both in a server-side language and then in javascript for the front-end does not make sense.

The developer community-created open source javascript frameworks based on React, which allow for the creation of javascript applications which render the page on the server and then enrich it with slick UI in the frontend. There are 2 most commonly used frameworks:

• Nextjs - https://nextjs.org/
• Gatsbyjs  - https://www.gatsbyjs.org/

Both of these offer similar functionality and allow building of super-fast websites assembled in the backend and working super smoothly in the frontend. 

From Drupal perspective, development of a headless CMS is identical for a typical single page application.

Loss of some of the Drupal functionality

Drupal out of the box provides a lot of functionality. If Drupal is kept in the backend, a lot of this is no longer available. In particular:

• Layout management  - drupal provides a highly configurable page layout management with region definition and an ability to place elements in various parts of the page without the need to code them in (eg placing a search window in the header or a menu in the footer). 
• Account management screens- Drupal provides register, login, password reset functionality out of the box. If we intend to allow users to register, we will have to implement all the forms and connect them to the APIs.
• Preview - If we create content in Drupal, we as an author can preview it before it is published. In a typical headless setup especially if content is available via many channels, the preview of all is not available. Often editor adds content without seeing the end result. If needed, it has to be separately architected and created to allow editors to preview their creations.

Summary

Headless Drupal is an interesting approach to build feature-rich interactive websites or build content hubs which power various content consuming websites and media. It is however not without disadvantages and careful consideration should be made before choosing this path. Hopefully, this article gave you sufficient information to chose. If not, we are always happy to consult your Drupal project.

Give us a shout!