RESTful Web Services in Drupal 8 quick start guide

Introduction

Headless Drupal is one of the most exciting topics that captured many minds in the last few years.

It’s a phenomenon closely related to RESTful API (also known as web services) - another popular term. It gives a wide range of new abilities for us as developers. We will look under the hood of the web services, how they work and how they can be used, go through the list of available tools. At the end of the article, we will use Drupal 8 Core REST API to create a node. So let’s try to deal with all those fancy words and determine how it can help us to make our sites better.

RESTful Web Services in Drupal 8 quick start guide 1

What is a Web Service?

A little bit about the Internet of things, mobile apps and other stuff

Assume you have two computers connected to the Internet, both are on the different continents. To communicate with each other they need a unified language. This is a key - the web service is a standardized way for two computers to interact. In the age of the ‘Internet of Things’ (IoT), anything connected to the Internet can be a computer (even your microwave oven).

So computers or devices can use the same API (an application program interface) to understand and interact with each other without any human intervention. We can use API’s in everyday life and don’t know about that (e.g. when we connect a phone to the computer).

For example, your mobile app can communicate with Drupal site to create a node or change and delete an existing one. That’s how it works: using REST API, the mobile app makes a request and Drupal site responds with structured data (e.g. JSON) which an external app can use. So, the external app can be a JavaScript framework, that used for front-end of site display, but all backend logics still belongs to Drupal. And even more...

REST is just another one way to make the Web Services work. There are also other formats such as XML-RPC, SOAP, etc.

Let’s take a look at REST abilities of Drupal 8.

Web Services in Drupal 8

In Drupal 8 Web Services work out of the box. That means you don’t need to download additional modules, all necessary tools are already implemented in the core with the following modules:

  • RESTful Web Services (rest): provides RESTful API that allows you to interact with any content entity such as nodes, comments, users. Depends on the Serialization module.
  • Serialization: a service for serialization of data to and from formats, such as JSON or XML. If you want to learn how to send the JSON data from a Drupal 8 site, read the article on this topic. 
  • Hypertext Application Language (hal): HAL is a hypermedia format which is a primary format in the Drupal 8 Core. Can be encoded in JSON or XML.
  • HTTP Basic Authentication (basic_auth): provides a basic user authentication.

Drupal 8 is much simpler than the 7th version of this CMS. Find out other differences here and also try to build your custom module using Drupal 8

The shortest answer is doing the thing.
- Ernest Hemingway

Example

First of all, you need to enable the modules listed above. With a little help from the REST module, you easily can do GET, POST, DELETE and PATCH operations on node entity resource.

Some words about HTTP request methods: when you open a page in your preferred web browser it uses the GET method to read a resource, retrieve data and give it back to you. If you want to create the resource on a server you need to use POST. The DELETE method deletes the specified resource. PATCH is used for the update.

So these are basic methods that will help us to interact with entities on our Drupal site. To use them you need to install a browser extension. I’m using Restlet Client - DHC for this purpose. My version of Drupal is 8.2.6.

Let’s try to create a node. In the request BODY, we set a type and a title of the created node. Content-Type header is set to application/hal+json. This is how POST to the URL /entity/node looks like:

Restlet Client:

RESTful Web Services in Drupal 8 quick start guide 2

cURL (command line):

curl --include \

 --request POST \

 --user admin:secret \

 --header 'Content-type: application/hal+json' \

 --header 'X-CSRF-Token: <obtained from http://example.com/rest/session/token>' \

 http://example.com/entity/node?_format=hal_json \

 --data-binary '{"_links":{"type":{"href":"http://drupal8.dev/rest/type/node/article"}},"title":[{"value":"My first article"}],"type":[{"target_id":"article"}]}'

Let me notice some things about CSRF token: you can get this token by the GET request to rest/session/token and send it with your POST request.

If done correctly you should see the nice green 201 Created response.

RESTful Web Services in Drupal 8 quick start guide 3

Conclusion

Now you should have an understanding of REST Web Services in Drupal 8 and how you can manipulate basic Drupal entities such as a node through REST API. And it is just the beginning. I hope this knowledge will help you in your own further exploration.

Useful links: 

1. OOP in Drupal 8 and how to use it to create a custom module

2. Why you should migrate your site to Drupal

3. How to create a headless Drupal site

4. How to send the JSON data from a Drupal 8 site?

You might also like