Content publishing on Drupal 8.2 through RESTful Web services

Submitted by Juan on Tue, 11/29/2016 - 16:17
Old typewriting machine

I have decided to write this entry because in the past few days I exploring the RESTful module of Drupal 8 to publish some contents from an outer source and I found myself on a confusing situation, even when there are already many tutorials and documentation about it, which however may have become already obsolete in certain way as the RESTful module has transformed since the beginning (as the one and only Dries Buytaert explained in his website). I'm talking in particular of the task of creating a new node through the POST method on Drupal 8.2.3. I won't approach the labor of querying existing content with the GET method because that's a simpler task where the current documentation is already clear and useful.

The first task is to activate the following modules already included as part of the Drupal core:

  • RESTful Web Services
  • HAL
  • HTTP Basic Authentication
  • Serialization

And to make our life easier and don't get involved with YAML configuration files, install the next contributed module:

  • REST UI

Now we have to create a user account which will be used for web service authentication. This user account must have the right permissions to watch an create new contents for the content type we are intending to create through REST. This last step is something changed on recent Drupal core updates, as before we had to assign permissions per action (GET, POST, PATCH or DELETE) in the REST Web Services permissions section.

The next step is to activate the REST actions for the resources we are interested in, and we navigate to Configuration / REST or http://yourwebsite.com/admin/config/services/rest.

As default the Content resource with the path pattern /node/{node} is already activated. We click on the Edit option of this resource and activate POST with the hal_json format and basic_auth provider checked:

Configuración del módulo REST UI

Now we request from Drupal one last thing before we go to the client configuration: an X-CSRF authentication token. We ask for it by opening the next URL in the web browser:

http://yourwebsite.com/rest/session/token

This will give us a hash string similar to the next one. Copy that to the clipboard, we'll need it later when setting up the client:

BB7-E8HR2E9JHSSq2ggfdDdyIJC369MVGbE4AgbNHdI

We are now ready on the Drupal backend to request content via REST. I will use Postman for testing purposes even when it can be performed with any other client or script to do the request via HTTP.

The address we must point to must coincide with the URL pattern we were indicated on the REST configuration for the Content resource, I mean: http://yourwebsite.com/entity/node?_format=hal_json. As we are interested in creating a new content, we must choose the POST method.

One of the advantages of using Postman is that it generates an encrypted string which will be used to connect. Another alternative is to generate this string manually by encoding with base-64 the username and password from the Drupal account in the following format string: username:password.

Postman autorización

We will send the application/hal+json value on the Content-Type and Accept headers. The other two headers we are interested in are X-CSRF-TOKEN which value is the token string we did copy to the clipboard, and Authorization with the value: Basic followed by the base 64 encoded username and password:

Encabezados Postman

The request body is an Ajax string with the content type and node data we want to save:

{
	"_links": {
		"type": {
			"href": "http://fischer.dev:81/rest/type/node/article"
		}
	},
	"title": [
		{
			"value":"Node title"
		}
	],
	"body": [
		{
			"value":"Body of the node."
		}
	]
}

This is another part which has changed through the evolution of Drupal 8 and therefore in the documentation and the tutorials you can find on the web. If we don't use the correct structure our request will be broken.

We click the Send button on Postman and we must receive an 201 Created status beside a JSON document with the information of the newly created node. In case you get and empty response or 403 Forbidden status maybe it's worth review the permissions of the user account you are using to authenticate and the JSON structure of the request body, being sure of being specifying correctly the content type of the node you want to generate.