Improving Drupal 8's API-first: JSON API and OAuth2?
Recommended next steps for Drupal 8's API-first initiative; including JSON API and OAuth2 in Drupal 8 core.
Among the most important initiatives for Drupal 8's future is the "API-first initiative", whose goal is to improve Drupal's web services capabilities for building decoupled applications. In my previous blog posts, I evaluated the current state of, outlined a vision for, and mapped a path forward for Drupal's web services solutions.
In the five months since my last update, web services in Drupal have moved forward substantially in functionality and ease of use. This blog post discusses the biggest improvements.
Core REST improvements
With the release of Drupal 8.2, the core REST API now supports important requirements for decoupled applications. First, you can now retrieve configuration entities (such as blocks and menus) as REST resources. You can also conduct user registration through the REST API. The developer experience of core REST has improved as well, with simplified REST configuration and better response messages and status codes for requests causing errors.
All of these improvements are thanks to the hard work of Wim Leers (Acquia), Ted Bowman (Acquia), Daniel Wehner (Chapter Three), Clemens Tolboom, José Manuel Rodríguez Vélez, Klaus Purer, James Gilliland (APQC), and Gabe Sullice (Aten Design Group).
JSON API as an emerging standard
JSON API is a specification for REST APIs in JSON which offers several compelling advantages over the current core REST API. First, JSON API provides a standard way to query not only single entities but also all relationships tied to that entity and to perform query operations through query string parameters (for example, listing all tags associated with an article). Second, JSON API allows you to fetch lists of content entities (including filtering, sorting and paging), whereas the only options for this currently available in core are to issue multiple requests, which is undesirable for performance, or to query Drupal views, which require additional work to create.
Thanks to the efforts of Mateu Aguiló Bosch (Lullabot) and Gabe Sullice (Aten Design Group), the JSON API module in Drupal 8 is quickly approaching a level of stability that could put it under consideration as a core experimental module.
OAuth2 bearer token authentication
One of the issues facing many decoupled applications today is the lack of a robust authentication mechanism when working with Drupal's REST API. Currently, core REST only has two options available out of the box, namely cookie-based authentication, which is unhelpful for decoupled applications on domains other than the Drupal site, and basic authentication, which is less secure than other mechanisms.
Due to its wide acceptance, OAuth2 seems a logical next step for Drupal sites that need to authenticate requests. Because it is more secure than what is available in core REST's basic authentication, OAuth2 would help developers build more secure decoupled Drupal architectures and allow us to deprecate the other less secure approaches.
It would make sense to see an OAuth2 solution such as Simple OAuth, the work of Mateu Aguiló Bosch (Lullabot), as an experimental core module, so that we can make REST APIs in Drupal more secure.
Waterwheel, Drupal's SDK ecosystem
Thanks to the hard work of the many contributors involved, the API-first initiative is progressing with great momentum. In this post, we ended with the following conclusions:
- The JSON API and Simple OAuth modules could be candidates for inclusion in Drupal 8 core — this is something we should discuss and evaluate.
- We should discuss where support for HAL and JSON API stops and starts, because it helps us focus our time and effort.
If you are building decoupled applications with Drupal 8, we would benefit significantly from your impressions of the core REST API and JSON API implementations now available. What features are missing? What queries are difficult or need work? How can we make the APIs more suited to your requirements? Use the comments section on this blog post to tell us more about the work you are doing so we can learn from your experiences.
Of course, if you can help accelerate the work of the API-first initiative by contributing code, reviewing and testing patches, or merely by participating in the discussions within the issues, you will not only be helping improve Drupal itself; you'll be helping improve the experience of all developers who wish to use Drupal as their ideal API-first back end.
Special thanks to Preston So for contributions to this blog post and to Wim Leers, Angie Byron, Ted Bowman and Chris Hamper for their feedback during the writing process.
— Dries Buytaert
Dries Buytaert is an Open Source advocate and technology executive. More than 10,000 people are subscribed to his blog. Sign up to have new posts emailed to you or subscribe using RSS. Write to Dries Buytaert at firstname.lastname@example.org.