1. Getting started: REST configuration & REST request fundamentals
RESTful Web Services API — Practical.
Now you know how to:
- expose data as REST resources
- grant the necessary permissions
- customize a REST resource's formats (JSON, XML, HAL+JSON, CSV …)
- customize a REST resource's authentication mechanisms (cookie, OAuth, OAuth 2.0 Token Bearer, HTTP Basic Authentication …)
Armed with that knowledge, you can configure a Drupal 8 site to expose data to precisely match your needs.
2. REST request fundamentals
2.1 Safe vs. unsafe methods
REST uses HTTP, and uses the HTTP verbs. The HTTP verbs (also called
request methods) are:
Some of these methods are safe: they are read-only. Hence they can never cause harm to the stored data, because they can't manipulate them. The safe methods are
All other methods are unsafe, because they perform writes, and can hence manipulate stored data.
PUT is not supported for good reasons.
2.2 Unsafe methods & CSRF protection:
X-CSRF-Token request header
Drupal 8 protects its REST resources from CSRF attacks by requiring a
X-CSRF-Token request header to be sent when using a non-safe method. So, when performing non-read-only requests, that token is required.
Such a token can be retrieved at
When performing REST requests, you must inform Drupal about the serialization format you are using (even if only one is supported for a given REST resource). So:
- Always specify the
?_formatquery argument, e.g.
- When sending a request body containing data in that format, specify the
Content-Typerequest header. This is the case for
Accept-header based content negotiation was removed from Drupal 8 because browsers and proxies had poor support for it.
Now you're ready to look at concrete examples, which start on the next page.