RESTful Web Services API overview

Last updated on
18 May 2017

The RESTful Web Services API is new in Drupal 8.

For each REST resource, you can specify the supported verbs, and for each verb, you can specify the serialization formats & authentication mechanisms.

This page is documenting capabilities of the REST module's API, about how to configure REST resource plugins, as well as how to create your own.

For information on how to actually consume the REST API from an application, see "1. Getting started: REST configuration & REST request fundamentals" — it is the first page of a complete how-to!

API features

Ordered by most to least frequently used APIs:

Configuring REST resources

Specific version(s)

Before Drupal 8.2, this used to live in rest.settings.yml. The configuration in there is migrated automatically when you update to Drupal 8.2 or later. For details, see the change record: "REST config converted to config entities".

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.
Each REST resource can be configured in its config entity: you can configure which HTTP methods, serialization formats & authentication mechanisms it supports. The same serialization formats and authentication mechanisms are then supported on all of its methods.
Install the REST UI contributed module to configure REST resources. (Or, if you want to modify & import config YAML by hand, look at m core/modules/rest/config/optional/rest.resource.entity.node.yml to get started!)
Resource plugins
\Drupal\rest\Plugin\ResourceInterface: resource plugins, to expose additional resources over REST.
The above allows Drupal to automatically expose that resource using REST, using any authentication mechanism (see Authentication API for details), and any serialization format (both encoding & normalization — see Serialization API for details). So as a developer, you only need to implement the logic to work with the object in question that you're exposing as a resource.

Practical: how you'll typically use REST

Typically, you 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.

Configure REST resources
Expose the REST resources you want — see Configuring REST resources above.
The most common use case: interacting with entities. For REST resources exposing entities, the Entity Access API determines whether entities can be interacted with. For example, users must have the access content permission to be able to GET a Node entity (view it), and the create article contentpermission to be able to POST an article Node (create it).
 

Specific version(s)

Before Drupal 8.2, one had to grant REST-specific permissions on top of the necessary entity type-specific permissions. Ror details, see the change record: "Accessing entities via REST no longer requires additional REST-specific permissions".

Customize a REST resource's formats
By default, the REST module supports json and xml. If you install core's HAL module, you can also enable the hal_json format. By installing additional modules, you can get access to more formats — see Serialization API for details.
Do it via the REST UI module, or modify config directly:
granularity: resource
configuration:
  methods:
    - …
  formats:
    - hal_json
    - xml
    - json
  authentication:
    - …
Customize a REST resource's authentication mechanism
In case of an authenticated user and a progressively decoupled Drupal site, you probably want authentication to happen using the cookie that the authenticated user already has.
Do it via the REST UI module, or modify config directly:
granularity: resource
configuration:
  methods:
    - …
  formats:
    - …
  authentication:
    - cookie
Creating REST resource plugins
Look at \Drupal\dblog\Plugin\rest\resource\DBLogResource for a trivial example, \Drupal\rest\Plugin\rest\resource\EntityResource for a very complex example.
Note that scaffolding code for custom modules can be automatically generated with a Drupal Console command via drupal generate:plugin:rest:resource!
What is very important is the @RestResource annotation's uri_paths definition (which takes link relation types as keys, and partial URIs as values). If you don't specify any, Drupal will automatically generate URI paths (and hence URLs) based on the plugin ID. If your plugin ID is fancy_todo, you'll end up with GET|PATCH|DELETE /fancy_todo/{id} and POST /fancy_todo. But, often, you'll want to specify your own paths: a canonical URI path (for example /todo/{todo_id}), but also a https://www.drupal.org/link-relations/create URI path (for example /todo). For example:
 *   uri_paths = {
 *     "canonical" = "/todo/{id}",
 *     "https://www.drupal.org/link-relations/create" = "/todo"
 *   }

This also allows you to version your API, and create different implementations for each version:

 *   uri_paths = {
 *     "canonical" = "/api/v1//todo/{id}",
 *     "https://www.drupal.org/link-relations/create" = "/api/v1/todo"
 *   }