Getting started: REST configuration & REST request fundamentals
Configuration
First read 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.
REST request fundamentals
Safe vs. unsafe methods
REST uses HTTP, and uses the HTTP verbs. The HTTP verbs (also called request methods) are: GET
, HEAD
, POST
, PUT
, DELETE
, TRACE
, OPTIONS
, CONNECT
and PATCH
.
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 it. The safe methods are HEAD
, GET
, OPTIONS
and TRACE
.
All other methods are unsafe, because they perform writes, and can hence manipulate stored data.
Note: PUT
is not supported for good reasons.
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 /session/token
.
Format
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
?_format
query argument, e.g.http://example.com/node/1?_format=json
. - When sending a request body containing data in that format, specify the
Content-Type
request header. This is the case forPOST
andPATCH
.
Accept
-header based content negotiation was removed from Drupal 8 because browsers and proxies had poor support for it.
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion