The RESTful Web Services module provides routes that expose endpoints for your RESTful API. It utilizes the Serialization module to handle the normalization to a response and denormalization of data from requests. Endpoints support specific formats and authentication providers.
There is one caveat: RESTful Web Services does not provide a user interface and relies on a single configuration object to enable RESTful endpoints for content entities. Individual endpoints are not their own configuration entities.
When the RESTful Web Services module is first installed, it will enable GET, POST, PATCH, and DELETE methods for the node entity. Each method will support the hal_json format and basic_auth for its support authentication methods. This ends up with a highly coupled relationship between the HAL and HTTP Basic Authentication modules.
In this recipe, we will install RESTful Web Services and enable the proper permissions to allow the retrieval of nodes via REST to receive our formatted JSON.
There is a configuration change that might be required if you are running PHP 5.6, the always_populate_raw_post_data setting. If you try to enable the RESTful Web Services module without changing the default setting, you will see the following error message on installation:
The always_populate_raw_post_data PHP setting should be set to -1 in PHP version 5.6. Please check the PHP manual for information on how to correct this. (Currently using always_populate_raw_post_data PHP setting version Not set to -1.)
You will need to modify your PHP's configuration to set always_populate_raw_post_data to -1.
- Visit Extend from the administrative toolbar and install the Web Services modules: Serialization, RESTful Web Services, and HAL:
- The RESTful Web Services module provides the default installation configuration in its
config/install/rest.settings.ymlfile. This enables theentity:nodeendpoint, allowing it to be manipulated over a RESTful interface:resources: entity:node: GET: supported_formats: - hal_json supported_auth: - basic_auth POST: supported_formats: - hal_json supported_auth: - basic_auth PATCH: supported_formats: - hal_json supported_auth: - basic_auth DELETE: supported_formats: - hal_json supported_auth: - basic_auth - In the
rest.settingsconfiguration namespace, there is a resources section. Each enabled RESTful interface resides under anentity:ENTITY_TYPEformat with each HTTP method it supports. ThisYAMLsettings enablesGET,POST,PATCH, andDELETEusing HAL JSON and Basic Auth. - The RESTful Web Services module exposes each
HTTPmethod as a permission for each endpoint. Visit the Permissions form from the People page. - Enable the Access GET on Content resource permission for anonymous and authenticated users:
- Additionally, you can enable
DELETE,PATCH, andPOSTon other roles, such as authenticated users. - Save the permissions form. Node entities are now available in REST endpoints.
The RESTful Web Services module works by implementing an event subscriber service, rest.resource_routes, that adds routes to Drupal based on implementations of its RestResource plugin. Each plugin returns the available routes based on HTTP methods that are enabled for the resource.
When routes are built, the Drupal
estRoutingResourceRoutes class uses the RestResource plugin manager to retrieve all the available definitions. The rest.settings configuration object is loaded and inspected. If the resource plugin provides an HTTP method that is enabled in the rest.settings.resources definitions, it begins to build a new route. Verification is done against the defined supported formats and supported auth definitions. If the basic validation passes, the new route is added to the RouteCollection and returned.
If you provide a supported_formats or supported_auth value that is not available, the endpoint will still be created. There will be an error, however, if you attempt to use the route with the invalid plugin. For example, routes need to define an authentication provider key, whether it is a disabled provider or an empty YAML array.
The RESTful Web Services module provides a robust API that has some additional items to make a note of. We will explore these in the next recipe.
For all intents and purposes, the HAL module is not technically a dependency when you install the RESTful Web Services module. The issue, however, resides in the fact that the default installation configuration sets the allowed format to hal_json. In the event that the HAL module is not enabled, an error will be thrown using the default node endpoint configuration.
There is work being done in the Drupal core issue queue to resolve the high coupling of the web services modules.
The RESTful Web Services module defines a RestResource plugin. This plugin is used to define resource endpoints. They are discovered in a module's Plugin/rest/resource namespace and need to implement the Drupal
estPluginResourceInterface interface.
Drupal 8 provides two implementations of the RestResource plugin. The first is the EntityResource class that is provided by the RESTful Web Services module. It implements a driver class that allows it to represent each entity type. The second is the Database Logging module that provides its own RestResource plugin as well. It allows you to retrieve logged messages by IDs.
The Drupal
estPluginResourceBase class provides an abstract base class that can be extended for RestResource plugin implementations. If the child class provides a method that matches the available HTTP methods, it will support them. For example, if a class has only a get method, you can only interact with that endpoint through HTTP GET requests. On the other hand, you can provide a trace method that allows an endpoint to support HTTP TRACE requests.
As stated in the recipe's introduction, the RESTful Web Services module does not have a user interface to enable, disable, or configure REST endpoints. The REST UI module provides an interface to configure the available REST endpoints. While the interface is rudimentary, it provides a way to enable and disable content entity endpoints. You can then edit the endpoints and enable or disable the specific HTTP methods and their supported formats.
The REST UI module can be downloaded from Drupal.org at https://www.drupal.org/project/restui.
Many APIs implement a rate limit to prevent abuse of public APIs. When you have publicly exposed APIs, you need to control the amount of traffic hitting the service and prevent abusers from slowing down or stopping your service.
The Rate Limiter module implements multiple ways to control access to your public APIs. There is an option to control the rate limit on specific requests, IP address-based limiting, and IP whitelisting.
You can download the Rate Limiter module from https://www.drupal.org/project/rate_limiter.
- Refer to the Drupal.org documentation for the RESTful Web Services module at https://www.drupal.org/documentation/modules/rest
- Change record: Accept header based routing got replaced by a query parameter, https://www.drupal.org/node/2501221
- Chapter 7, Plug and Play with Plugins
- Refer to the Rate Limiter module at https://www.drupal.org/project/rate_limiter
- Refer to the REST UI module at https://www.drupal.org/project/restui