Blog/ What is headless Drupal?

Recently you must have heard of the term "headless Drupal". You may be wondering what exactly it is. How is it different than standard Drupal and how can you implement it? If these are the questions that are plaguing you, then this is the post for you.

Conceptually headless Drupal is pretty simple. It involves two changes from standard Drupal:

1. Instead of spitting out HTML, Drupal spits out data in JSON format.
2. A front-end UI framework, such as AngularJS, EmberJS or React, renders the data to create a webpage.

Why do you need headless Drupal?

As you must be aware, recently there has been an explosion of front-end JS frameworks and Drupal's UI has not been able to catch up with it. With headless Drupal, you get the best of both worlds. You can use a new JS front-end framework backed by Drupal's reliability and flexibility in the back-end. That said, there are multiple ways you can implement this, depending on how integrated your UI is with Drupal. Here are two ways that are popular:

1) Drupal is totally de-coupled from front-end UI.

In this case, front-end UI doesn't really care what the back-end technology is. It only cares about the APIs that the back-end is exposing. Here's a very simple example: in the front-end, you have a plain HTML file with some JS. When this HTML page loads, JS executes a back-end API call to get the data. Usually, you will parse the URL and pass in the id (for e.g. node id) to the back-end in the API call. On the back-end, Drupal uses Services or RestWS module to respond to the request received from the HTML file. Instead of responding with HTML, it returns JSON back to the HTML file. Now JS in the HTML file parses the received JSON and renders it to create the full HTML page. Advantage of this approach is that the back-end is totally decoupled from front-end. So you can replace Drupal with any other technology in future, or Drupal 8 for that matter, without making any change to the front-end as long as the APIs remain the same.

2) Drupal renders the HTML page in the above example.

The above scenario will work very well if data that the HTML file is requesting is available to anonymous users. For authenticated users, it gets slightly more complicated. If your HTML file is on a different domain than Drupal's, JS will first need to make a back-end call to log in and then make a second call to get the data. On the other hand if your HTML file is on the same domain as Drupal's, then you are essentially doing theming twice. Irrespective of the page you are on, you want the site layout and template to look similar. If Drupal is completely decoupled from the front-end for some pages, then on those pages, you will need to make the same theme/template on front-end HTML file as the one Drupal has. To avoid this, you can let Drupal respond with the base HTML with the same JS and let the JS call Drupal's API on page load. As an example, you want to implement the headless Drupal technique on the page /ui. First you create this page callback in hook_menu(), then create an html--ui.tpl.php which has all the regions that you need on the page. Usually you will keep the header and footer so that the page looks part of the same site. Now using a preprocess function, add the relevant JS on that page. This is the JS which will call Drupal's API endpoint to get data in JSON format. The advantage of this approach is that since the HTML is being rendered by Drupal, you will not need to duplicate the theming work and if the user is authenticated in Drupal, then he will be authenticated to make the back-end API call as well. There is no need for him to log in through the Services first (you'll need to enable SESSION authentication in services for this). The disadvantage of this approach is that in future, if you want to replace Drupal by some other technology, then front-end will need to be replaced as well.

In next articles, we'll take you through a series of steps starting with the simplest example of headless Drupal and ending with a full application that uses a front-end JS framework communicating with Drupal using APIs. You can also look at our post on integrating AngularJS with Drupal which provides an example of building a calendar using option 2 above.