From RESTful Web Services API overview:
The RESTful Web Services API is new in Drupal 8. Expose entities as REST resources either to build a decoupled Drupal site, to let a native mobile iOS/Android app talk consume/feed a Drupal site, or to integrate with some web service.
The following Web Services modules are available in core:
- HAL - Serializes entities using Hypertext Application Language.
- HTTP Basic Authentication - Provides the HTTP Basic authentication provider based on Drupal user names and passwords.
- RESTful Web Services - Enables Web Services
- Serialization - Serializes data via xml/json.
GET
- Request data from a URIHEAD
- Retrieve headers from a URIOPTIONS
- Request available communication optionsTRACE
- Echoes back request sent to server
CONNECT
- Opens a raw connection to a host through a proxy chainDELETE
- Requests that a server delete the resource at URIPATCH
- Request changes on a URIPOST
- Submit data to a URIPUT
- Request submitted data be stored under a URI (currently not supported)
All unsafe methods require X-CSRF-Token
request header, which can be retrieved at /rest/session/token
.
From RESTful Web Services API overview:
- 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
.
From RESTful Web Services API overview:
basic
- The quickest way to get started is to use basic HTTP Authentication. Enable the Basic Auth module found in core, then send your drupal username and password using HTTP Authorization Headerscookie
- Use the cookie granted to an authenticated user.
You can also use third-party modules to provide support for other authentication such as OAuth.
Note: These instructions are for Drupal 8.2 and later. See RESTful Web Services API overview for information on configuring Drupal 8.0 & 8.1.
Configurations are managed with YAML but can setup via REST UI module.
From RESTful Web Services API overview:
Each REST resource has a
\Drupal\rest\RestResourceConfigInterface
config entity that corresponds to a@RestResource
plugin. Without such a config entity, the REST resource plugin will not be available for use.There are two methods for configuring resources:
granularity: method
: Set serialization formats and authentication per HTTP method.granularity: resource
: Set serialization formats and authentication per resource.
Examples:
...
granularity: method
configuration:
GET:
supported_formats:
- json
supported_auth:
- basic_auth
- cookie
...
...
granularity: resource
configuration:
methods:
- GET
...
formats:
- json
...
authentication:
- basic_auth
...
Using lessons learned in 2.7 - Configuration Management, import the following configuration, specifying REST resource configuration
as the configuration type:
id: entity.node
plugin_id: 'entity:node'
granularity: resource
configuration:
methods:
- GET
- POST
- PATCH
- DELETE
formats:
- json
- hal_json
- xml
authentication:
- basic_auth
- cookie
The above configuration supports GET
/POST
/PATCH
/DELETE
requests.
Since this creates a generic endpoint, this data can now be consumed by any number of languages, frameworks and applications. The following examples illustrate a few different options:
Assuming you have a node previously setup with nid
of 1, you can test this by navigating to /node/1?_format=json
in your browser. If setup correctly, you should see your node represented by JSON instead of HTML.
For more detailed examples, see GET for updating content entities example.
x_csrf_token=$(curl --silent http://localhost:8888/rest/session/token)
curl --include \
--request POST \
--user admin:password \
--header 'Content-type: application/hal+json' \
--header "X-CSRF-Token: $x_csrf_token" \
http://localhost:8888/entity/node?_format=hal_json \
--data-binary '{"_links":{"type":{"href":"http://localhost:8888/rest/type/node/article"}},"title":[{"value":"My Node Title"}],"type":[{"target_id":"article"}]}'
Notes:
- This example requires the HAL module
- For security reasons it is considered bad practice to type passwords directly into your terminal. More secure methods of authentication should be considered.
For more detailed examples, see POST for updating content entities example.
function getCsrfToken(callback) {
jQuery
.get(Drupal.url('rest/session/token'))
.done(function (data) {
var csrfToken = data;
callback(csrfToken);
});
}
function patchNode(csrfToken, node) {
jQuery.ajax({
url: 'http://localhost:8888/node/1?_format=hal_json',
method: 'PATCH',
headers: {
'Content-Type': 'application/hal+json',
'X-CSRF-Token': csrfToken
},
data: JSON.stringify(node),
success: function (node) {
console.log(node);
}
});
}
var newNode = {
_links: {
type: {
href: 'http://localhost:8888/rest/type/node/article'
}
},
type: {
target_id: 'article'
},
title: {
value: 'This is my brand new title'
}
};
getCsrfToken(function (csrfToken) {
patchNode(csrfToken, newNode);
});
Notes:
- This example requires the HAL module
- This example assumed cookie-based authentication, which means you need to be running under the same domain name.
For more detailed examples, see PATCH for updating content entities example.
<?php
$response = \Drupal::httpClient()
->delete('http://localhost:8888/node/1?_format=json', [
'auth' => ['admin', 'password'],
'body' => '',
'headers' => [
'X-CSRF-Token' => $x_csrf_token
],
]);
?>
Notes:
- This example assumes you already have the
$x_csrf_token
value to the value from/rest/session/token
.
For more detailed examples, see DELETE for updating content entities example
To expose a view via Web Services:
- Edit your view.
- Under
Displays
click+ Add
and selectREST export
. - Under
Path Settings
set a path for your export. - You can adjust various settings in regards to format and fields to display as you would with any other view.
- Once you are finished, save your view
- Navigate to the path specified above in your browser. If everything went as expected, you should see your via in your specified format:
- drupal.org - RESTful Web Services API overview
- drupal.org - RESTful Web Services module overview
- drupal.org - Authentication API
- w3.org - HTTP 1.1/Method Definitions