RESTful Web Services API overview

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.

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 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.

• Plugin implementations must be annotated with the @RestResource annotation so they can be discovered.
• Discovered plugins' annotation metadata can be altered using hook_rest_resource_alter.
• \Drupal\rest\Plugin\ResourceBase provides a default implementation so resource plugins don't need to implement every method.

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. For 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 contrib 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} , but there will not automatically be support for POST requests.  To support POST requests, you must add a create path; you can override the default canonical URI path, as well. For example:

 *   uri_paths = {
 *     "canonical" = "/todo/{id}",
 *     "create" = "/todo"
 *   }

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

 *   uri_paths = {
 *     "canonical" = "/api/v1/todo/{id}",
 *     "create" = "/api/v1/todo"
 *   }

Drupal 9 and previous used the following format:

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

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

There annotations are only honored at the time the API is installed. If you change them, you have to uninstall and reinstall the API. You can also use the config/optional settings.yml file. Check ./modules/rest/config/optional/rest.resource.entity.node.yml for examples.

Issues to watch

Why https://www.drupal.org/link-relations/create?