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
.
config/install/rest.settings.yml
file. This enables the entity:node
endpoint, 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
rest.settings
configuration namespace, there is a resources section. Each enabled RESTful interface resides under an entity:ENTITY_TYPE
format with each HTTP method it supports. This YAML
settings enables GET
, POST
, PATCH
, and DELETE
using HAL JSON and Basic Auth.HTTP
method as a permission for each endpoint. Visit the Permissions form from the People page.DELETE
, PATCH
, and POST
on other roles, such as authenticated users.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
.