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?
If there is no theme, how is my content shown?
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.
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.
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.
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.
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.