REST module status report

klausi's picture

Here is a status report on the work that has been going into the Restful Web Services module for Drupal 8.

tl;dr: The implementation is well under way with basic operations working including routing, serialization and simpletests. There is still quite some work ahead of us to make the module more useful in real world scenarios.

Read the initial post about REST module first if you are not familiar with this effort. I would like to thank Acquia and epiqo again who have extended their sponsorship so that I can get further things done in the Drupal 8 feature completion phase.

So what are the accomplishments so far?

  • REST module uses a plugin architecture to connect internal data sources with a web API interface as so called resources. It comes with a default resource implementation for Drupal entities and an example resource implementation for Watchdog dblog entries. Plugins are flexible, they can decide what operation they want to support (example: HTTP GET to deliver a resource representation). Plugins can make use of an abstract base class that provides sensible defaults for the exposed routes, permissions and available operations, but they can also override that completely.
  • Resource plugins are serialization agnostic. That means that they don't have to care about the format of incoming or outgoing data. Example: an incoming POST request carrying a JSON-LD body is deserialized before it is passed to the resource plugin. Example: an outgoing GET response carrying a data object is serialized automatically to XML before it is actually send to the client. The big advantage here is that as soon as a new serialization format is added it is automatically available for all existing resource plugins, they don't have to be modified.
  • Support for HTTP DELETE requests to delete an entity, HTTP GET to retrieve an entity and HTTP POST to create an entity have been committed to Drupal 8 already. Support for HTTP PUT to replace an entity and HTTP PATCH to make partial updates on an entity are available as patches already.
  • Full test coverage with Simpletest's cURL client has been committed with all patches.
  • The benefits of our new routing system are leveraged by REST module. Example: GET request routes are restricted to the available JSON-LD media type, so they can potentially live on the same URL path as a route that returns the usual HTML. Example: it is possible to have two routes on /node/123, depending on the HTTP Accept headers set by the client Drupal will either return the HTML (for browsers) or the JSON-LD (for web service consumers) representation of node 123. (However, we currently do not leverage that as the implementation uses the path /entity/node/123 as suggested in the canonical URI discussion.)

What is left to do?

  • Finishing the work on PUT and PATCH requests to update entities.
  • Other formats: we are currently a bit tied to JSON-LD and should make other serialization formats configurable.
  • Extended configuration options: Enabling just one format on one operation on one resource plugin for example. See http://drupal.org/node/1850734
  • Field level access: Often it is not practical to grant full access to an entity resource, but to parts only. We should respect field/property access restrictions. That on the other hand requires a full user login and a populated global $user object to make the usual access checks work. That again is a problem for alternative authentication providers that have no relation to the Drupal user account system. Should an OAuth contrib module create fake sub-user accounts to make this work?
  • Collection support: while REST module only supports single entity operations there is an effort to leverage Views to provide lists of items.
  • Entity validation: Instead of blindly accepting any values to create/update entities we should integrate the upcoming entity validation system.
  • Documentation: REST module will need a dedicated documentation page with examples and a change notice for developers that informs them of this new power.
  • Another authentication mechanism: it was suggested that we could include HTTP basic authentication in Drupal core as alternative authentication mechanism to HTTP cookies.
  • Guzzle: the Simpletests for REST module could use Guzzle as HTTP client.
  • Entity revision support: we have an interface plan to deal with revisions, but this is surely no small task: http://groups.drupal.org/node/264568

As always I need your help to get this done. Feel free to jump in where you want and take part in the REST issue queue.

Thanks

As credit is the currency in an open source project, let me make a personal thank you payment here:

... and all others that I forgot right now. Sorry ;-)