Drupal 8 ships with the RESTful Web Services module which allows you to expose various API endpoints for interacting with your Drupal site. While the community is making a push for the JSON API module, I have found the core' RESTful module to be pretty useful when I have custom endpoints or need to implement Remote Procedure Calls (RPC) endpoints. However, using the module and enabling endpoints is a bit rough. So, let's cover that! Also note, this blog covers the content from the introduction of the Web Services chapter from the Drupal 8 Development Cookbook.

For the curious: RESTful stands for Representational state transfer. It's about building APIs limited to the constraints of the HTTP definition itself. It's stateless and allows does not require you to build a super custom client when working with the API. If you want to nerd out, read Roy Thomas Fielding's dissertation which describes the REST architecture.

Let's get started!

So, there is one major problem with the core RESTful Web Services module. It has no user interface. Yep, that's right. A Drupal component without a user interface out of the box, I didn't believe when I wrote my book the first time nor the second. Luckily, there is a module for that (the Drupal way.) You can either manually edit config through the means of your choice, or grab the REST UI module. The REST UI module provides a user interface to enable and modify API endpoints provides by the RESTful Web Services module.

First things first, we need to add the REST UI module to our Drupal site.

cd /path/to/drupal8
composer require drupal/restui

If you are new to Composer, here's an example screenshot of the output from when I ran the command.

Now that the module has been added to Drupal, let's go install the modules. Go on and log into your Drupal site. Then head over to Extend via the administrative toolbar and install the following Web services modules: Serialization, RESTful Web Services, and REST UI. Although not needed, I'm also going to install HTTP Basic Authentication to show off what it looks like to configure authentication providers (covered properly in the book.)

Click on Install to get the modules all settled into Drupal and available. Once you see that green message 4 modules have been enabled: HTTP Basic Authentication, RESTful Web Services, Serialization, REST UI. we are good to go to move to the next step!

Configuration: enabling and modifying endpoints

Yay! We have modules installed, we can begin to get all decoupled, or progressively decoupled. Go to Configuration and click on REST under Web Services to configure the available endpoints. To expose content (nodes) over the API, click on Enable for the Content row.

With the endpoint enabled, it must be configured. Check the GET method checkbox to allow GET requests. Then, check the json checkbox so that data can be returned as JSON. All endpoints require a selected authentication provider. Check the cookie checkbox, and then save it. This gives us an endpoint to read content that returns a JSON payload.

Go ahead and click Save configuration to finish enabling the endpoint. Also note, any RESTful resource endpoint enabled will use the same create, update, delete, and view permissions that have been already configured for the entity type. In order to allow anonymous access over GET for content,

Testing it out!

Give it a test run! Using cURL on the command line, a piece of content can now be retrieved using the RESTful endpoint. You must add ?_format=json to the node's path to ensure that the proper format is returned.

Here's an example command

curl http://drupal8.ddev.local/node/1?_format=json

And its response (super truncated for space.)

{
    "nid": [
        {
            "value": 1
        }
    ],
    "uuid": [
        {
            "value": "1b92ceda-135e-4d7e-9861-bbe9a3ae1042"
        }
    ],
    "title": [
        {
            "value": "This is so stateless"
        }
    ],
    "uid": [
        {
            "target_id": 1,
            "target_type": "user",
            "target_uuid": "421f721e-d342-4505-b1b4-57849d480ace",
            "url": "\/user\/1"
        }
    ],
    "created": [
        {
            "value": "2018-04-26T02:44:54+00:00",
            "format": "Y-m-d\\TH:i:sP"
        }
    ],
    "changed": [
        {
            "value": "2018-04-26T02:45:23+00:00",
            "format": "Y-m-d\\TH:i:sP"
        }
    ],
    "body": [
        {
            "value": "\u003Cp\u003EIn my experience, there is no such thing as luck. What?! Hey, Luke! May the Force be with you. What good is a reward if you ain\u0027t around to use it? Besides, attacking that battle station ain\u0027t my idea of courage. It\u0027s more like\u2026suicide.\u003C\/p\u003E\r\n\r\n\u003Cp\u003ERemember, a Jedi can feel the Force flowing through him. The Force is strong with this one. I have you now.\u0026nbsp;\u003Cstrong\u003EHey, Luke!\u003C\/strong\u003E\u003Cem\u003EMay the Force be with you.\u003C\/em\u003E\u0026nbsp;He is here.\u003C\/p\u003E\r\n\r\n\u003Ch2\u003EDon\u0027t be too proud of this technological terror you\u0027ve constructed. The ability to destroy a planet is insignificant next to the power of the Force.\u003C\/h2\u003E\r\n\r\n\u003Cp\u003EDon\u0027t be too proud of this technological terror you\u0027ve constructed. The ability to destroy a planet is insignificant next to the power of the Force. He is here. Ye-ha! Ye-ha! I have traced the Rebel spies to her. Now she is my only link to finding their secret base.\u003C\/p\u003E\r\n",
            "format": "full_html",
            "processed": "\u003Cp\u003EIn my experience, there is no such thing as luck. What?! Hey, Luke! May the Force be with you. What good is a reward if you ain\u0027t around to use it? Besides, attacking that battle station ain\u0027t my idea of courage. It\u0027s more like\u2026suicide.\u003C\/p\u003E\n\n\u003Cp\u003ERemember, a Jedi can feel the Force flowing through him. The Force is strong with this one. I have you now.\u00a0\u003Cstrong\u003EHey, Luke!\u003C\/strong\u003E\u003Cem\u003EMay the Force be with you.\u003C\/em\u003E\u00a0He is here.\u003C\/p\u003E\n\n\u003Ch2\u003EDon\u0027t be too proud of this technological terror you\u0027ve constructed. The ability to destroy a planet is insignificant next to the power of the Force.\u003C\/h2\u003E\n\n\u003Cp\u003EDon\u0027t be too proud of this technological terror you\u0027ve constructed. The ability to destroy a planet is insignificant next to the power of the Force. He is here. Ye-ha! Ye-ha! I have traced the Rebel spies to her. Now she is my only link to finding their secret base.\u003C\/p\u003E\n",
            "summary": ""
        }
    ]
}

Woo! we did it! You can now consume content from your Drupal site from anything your dreams desire.

Want to know more?

There is a whole chapter in the Drupal 8 Development Cookbook on Web Services which covers the core RESTful Web Services module: GET, POST, PATCH, using Views, and Authentication. It also gives a brief introduction to the JSON API module.