REST and Application Integration

Same name in other branches
  1. 9 core/core.api.php \third_party
  2. 10 core/core.api.php \third_party
  3. 11.x core/core.api.php \third_party

Integrating third-party applications using REST and related operations.

Overview of web services

Web services make it possible for applications and web sites to read and update information from other web sites. There are several standard techniques for providing web services, including:

Drupal sites can both provide web services and integrate third-party web services.

Overview of REST

The REST technique uses basic HTTP requests to obtain and update data, where each web service defines a specific API (HTTP GET and/or POST parameters and returned response) for its HTTP requests. REST requests are separated into several types, known as methods, including:

  • GET: Requests to obtain data.
  • POST: Requests to update or create data.
  • PUT: Requests to update or create data (limited support, currently unused by entity resources).
  • PATCH: Requests to update a subset of data, such as one field.
  • DELETE: Requests to delete data.

The Drupal Core REST module provides support for GET, POST, PATCH, and DELETE quests on entities, GET requests on the database log from the Database Logging module, and a plugin framework for providing REST support for other data and other methods.

REST requests can be authenticated. The Drupal Core Basic Auth module provides authentication using the HTTP Basic protocol; the contributed module OAuth (https://www.drupal.org/project/oauth) implements the OAuth authentication protocol. You can also use cookie-based authentication, which would require users to be logged into the Drupal site while using the application on the third-party site that is using the REST service.

Enabling REST for entities and the log

Here are the steps to take to use the REST operations provided by Drupal Core:

  • Enable the REST module, plus Basic Auth (or another authentication method) and HAL.
  • Node entity support is configured by default. If you would like to support other types of entities, you can copy core/modules/rest/config/install/rest.settings.yml to your sync configuration directory, appropriately modified for other entity types, and import it. Support for GET on the log from the Database Logging module can also be enabled in this way; in this case, the 'entity:node' line in the configuration would be replaced by the appropriate plugin ID, 'dblog'.
  • Set up permissions to allow the desired REST operations for a role, and set up one or more user accounts to perform the operations.
  • To perform a REST operation, send a request to either the canonical URL for an entity (such as node/12345 for a node), or if the entity does not have a canonical URL, a URL like entity/(type)/(ID). The URL for a log entry is dblog/(ID). The request must have the following properties:

    • The request method must be set to the REST method you are using (POST, GET, PATCH, etc.).
    • The content type for the data you send, or the accept type for the data you are receiving, must be set to 'application/hal+json'.
    • If you are sending data, it must be JSON-encoded.
    • You'll also need to make sure the authentication information is sent with the request, unless you have allowed access to anonymous users.

For more detailed information on setting up REST, see https://www.drupal.org/documentation/modules/rest.

Defining new REST plugins

The REST framework in the REST module has support built in for entities, but it is also an extensible plugin-based system. REST plugins implement interface \Drupal\rest\Plugin\ResourceInterface, and generally extend base class \Drupal\rest\Plugin\ResourceBase. They are annotated with \Drupal\rest\Annotation\RestResource annotation, and must be in plugin namespace subdirectory Plugin\rest\resource. For more information on how to create plugins, see the Plugin API topic.

If you create a new REST plugin, you will also need to enable it by providing default configuration or configuration import, as outlined in Enabling REST for entities and the log above.

Integrating data from other sites into Drupal

If you want to integrate data from other web sites into Drupal, here are some notes:

File

core/core.api.php, line 72

Classes

Title Sort descending File name Summary
Json core/lib/Drupal/Component/Serialization/Json.php Default serialization for JSON.
ResourceBase core/modules/rest/src/Plugin/ResourceBase.php Common base class for resource plugins.
RestResource core/modules/rest/src/Annotation/RestResource.php Defines a REST resource annotation object.

Interfaces

Title Sort descending File name Summary
ResourceInterface core/modules/rest/src/Plugin/ResourceInterface.php Specifies the publicly available methods of a resource plugin.

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.