Manage several apps with one Drupal backend using Drupal 8's RESTful API for a headless Drupal

Thursday, July 14, 2016 by Jan Zavrl

You may have heard the phrase “headless Drupal”. You also may have heard about building a RESTful API with Drupal, but you’re not quite sure what that means or how these features can be utilised. No worries, in all honesty things are not as scary as they may appear and are also much simpler than they sound.

First things first: what is headless Drupal?

The phrase “headless” came into play pretty much alongside various Javascript frameworks such as AngularJS, ReactJS, KnockoutJS, to name a few. With a headless Drupal, we are only using the backend side of our Drupal application. The theme or frontend part is not being generated or shown to the user, at least not the Drupal one. So the main part - the head - is not being generated, thus “headless Drupal”.

If there is no theme, how is my content shown?

As I mentioned, headless Drupal always comes with a separate framework to display your content. This can be a Javascript framework on the web, iOS, Android application, etc. It can even be a Windows or OSX application if you wish. 
With this, the frontend can be anything you wish. It could even be several things at once. But the most important part is that the content editors only have one place for their content management.

Yes, this can require a bit more knowledge and work to make it happen, but the results are far more rewarding. You also need to know that if you create such a frontend, you create it from scratch.,meaning the application only has whatever it needs or whatever you put in it, of course. Still, this means no extra Javascripts files, no extra CSS files, and for me probably most importantly, no extra markup and classes. Any data can now only be wrapped in whatever you create. Yes, I’m looking at you: views, fields and co.

That’s great, but how do you get all that data into a JS framework. Isn’t Drupal a PHP based framework?

Indeed it is. And this is where the phrase “RESTful API” comes into play. For a slightly more in depth explanation, you can read it here. Basically, it works like this. On its own, it doesn’t do anything, but where you send a specific request to it, it will return data to you; or an error if you mistyped something. So, basically, in the real world this would look something like this.

“Hey API! I want to have the last 10 news titles, together with a short summary and published date. And while you’re at it, sort them by newest first.“

“Sure developer! Here you go.“

Yeah, it’s that simple. You basically do a GET request to a specific URL and in return you (normally) get a JSON response. It could also be something else, such as XML, but JSON is the most used and any respected JS framework supports it. You could also do a POST request to write data, and a DELETE request to delete data.

This is awesome! How do I get my hands dirty?

Well, with Drupal 7 you first needed the Services and Restful modules; however, seeing how Drupal 8 is awesome and badass, you’ve got everything you need in the core…. well, at least for the most part.

Headless Drupal

You start as with any other Drupal feature - you enable some modules. In our case, this would be the Serialization, RESTful Web Services and HTTP Basic Authentication modules. The module descriptions speak mostly for themselves. You could make things work without the HTTP Basic Authentication module, but that means you can only authenticate yourself using cookies. With this module, you can authenticate yourself using your own username and password out of the Drupal backend. It also provides you with a token that you can use.

So now that we have our modules ready, we can take a look at a setup. By default, you get enabled REST API on node entities for all operations using cookie authentication, and a JSON format. To view this configuration, open up the configuration file at sites/default/files/config_XXX/sync/rest.settings.yml. You can also edit the configuration. We need the authentication to work so we need to do that anyway. Open up the file, or if you’re more of a GUI person, you can use a great module called REST UI and do all the configuring with its user interface.

For starters, we will use the node entities, with the Basic Authentication and in JSON format. Your rest.settings.yml should look something like this.

resources:
  'entity:node':
    GET:
      supported_formats:
        - json
      supported_auth:
        - basic_auth
    POST:
      supported_formats:
        - json
      supported_auth:
        - basic_auth
    DELETE:
      supported_formats:
        - json
      supported_auth:
        - basic_auth
    PATCH:
      supported_formats:
        - json
      supported_auth:
        - basic_auth

So now let’s go and see how this works. Create some nodes on your installation or generate them using drush. Here I’ll be using a great Chrome addon tool called Dev HTTP Client to handle our requests and authentication. Essentially, what we are looking for is a GET request using some basic authentication.

Headless Drupal

This alone is enough to retrieve the data for node/1 entity. If you’ve done everything correct you should get a nice 200 response with a JSON file containing the properties and fields of the entity.

Headless Drupal

That’s a wrap

This is a very basic usage example, but you get the point. In principle it looks fairly simple, but is actually quite powerful. You can get any entity from the backend, you can create user accounts or taxonomy terms, you can also delete nodes if you’d like.

There are also other ways to authenticate yourself, such as OAuth, or even using a token by sending a GET request to rest/session/token and then adding an X-CSRF-Token header with the received token.

Drupal 8’s powerful REST API opens a great deal of options for developers and businesses. You don’t need to have several apps to utilize the REST API, it could just be your own portfolio, a corporate website, e-commerce etc.. 

The possibilities are endless.