The RESTful Web Services module's entity resource plugin implements a get method that is called when an HTTP GET request is made on an appropriate route. The entity is processed and then returned in the appropriate format requested.
In this recipe, we will enable the REST endpoint for taxonomy term entities through GET through both the JSON and HAL JSON formats. Since there is no user interface provided by the Drupal core to edit the RESTful Web Services settings, we will use a command-line tool to modify the values.
Note
Since both Drush and Console, as discussed in Chapter 9, Configuration Management – Deploying in Drupal 8, in the recipe Using command-line workflow processes, support manipulating configuration objects, this recipe will provide commands for both.
We will be modifying the rest.settings configuration object using command-line tools. You need to have either Drush or Drupal Console installed with the ability to manipulate your Drupal site.
If you are using Mac OS X and Vim is the default editor on the command line, you may experience difficulties. Vim does not always report its exit code as expected, and the command-line tool may not recognize that you have finished editing your code. Each command-line tool provides a method used to specify an editor (such as Nano).
We need to have a taxonomy vocabulary created with some terms so that there is data to be retrieved.
- Visit Extend from the administrative toolbar and install the Web Services modules:
Serialization,RESTful Web Services, andHAL. - Once the modules are installed, open a terminal and navigate to your Drupal site's directory.
- Edit the
rest.settingsconfiguration by running the appropriate configuration edit command:# For Drush drush config-edit rest.settings # For Console drupal config:edit rest.settings
- Once the editor is loaded, we need to add an
entity:taxonomy_termsection with a GET definition:resources: 'entity:taxonomy_term': GET: support_formats: - json - hal_json supported_auth: - cookie - The
entity:taxnomy_termpoints to the entity resource plugin's derivative for the taxonomy term entity. The definitions underGETprovide the supported formats, which can be returned, and supported authentications. - Commit the changes in your editor so that they can be imported into your Drupal site.
- We need to rebuild Drupal's routes for our endpoints to be activated, since the definition only lives in a configuration object:
# For Drush drush cache-rebuild # For Console drupal router:rebuild
- Console provides a way to rebuild the routing system, whereas with Drush you need to rebuild all caches.
- Visit the Permissions form from the People page. Enable the Access GET on Taxonomy term resource permission for anonymous and authenticated users.
- Access a taxonomy term by visiting your Drupal site with the
/taxonomy/term/1?_format=jsonpath. You will see the following response in your browser:{"message":"Not acceptable"} - In order to retrieve data through the endpoint, you need to pass the appropriate
Acceptheader. You can usecurlto simulate a request that passes this header:curl --request GET --url 'http://example.com/taxonomy/term/1?_format=json' --header 'accept: application/json'
- The command will return the formatted JSON with your taxonomy term's information.
The RESTful Web Services module compiles routes based on the rest.settings.resources values. When we implement a content entity endpoint, it actually adds a variation to the canonical URL. It allows us to specify a request format on the same path and have the data returned in that format.
The default routes provided by the Drupal
estPluginResourceBase class, the base class for resource plugins, return Drupal
estRequestHandler::handle for the controller. This method checks the passed _format parameter against the configured plugin. If the format is valid, the data is passed to the appropriate serializer.
The serialized data is then returned in the request with appropriate content headers.
There are details that involve the way in which a request is formulated to a Drupal web service resource. We will explore these now.
Early in the Drupal 8 life cycle, up until 8.0.0-beta12, Drupal supported the use of the Accept header instead of using the _format parameter. Unfortunately, there were issues with external caches since HTML and other formats are served on the same path, only having different Accept headers. The only solution to prevent cache poisoning on these external caches, such as Varnish, was to ensure the implementation of the Vary: Accept header. There were, however, too many issues regarding CDNs and variance of implementation, so the _format parameter was introduced instead of appending extensions (.json, .xml) to paths.
A detail of the problem can be found on these core issues:
- Refer to external caches mix up response formats on URLs where content negotiation is in use at https://www.drupal.org/node/2364011
- Check how to implement query parameter-based content negotiation as an alternative to extensions at https://www.drupal.org/node/2481453
- Refer to Change record:
Acceptheader-based routing got replaced by a query parameter at https://www.drupal.org/node/2501221 - Chapter 9, Configuration Management – Deploying in Drupal 8, in the recipe Using command-line workflow processes