Introducing Entity Query API for Drupal 8

Drupal 8 lays the foundation for building robust and flexible RESTful APIs quickly and efficiently. Combine this with Drupal’s best-in-class fieldable entity model and it becomes incredibly easy to construct systems that solve many different problems well.

Out of the box, Drupal 8 comes with core modules for all of the standard RESTful HTTP methods, GET, POST, PATCH, and DELETE. These endpoints are entity specific. Collection endpoints - endpoints that deal with entities in aggregate - are another story. The solution offered is the Views module.

In a headless or API intensive site however, core Drupal 8 and Views are limited by a major shortcoming. Support for querying your entity content over an API is limited to only the custom views that you create. This means that you must first create a view for any content that you want to expose. Filtering is limited to only the filters you explicitly enable and there’s no clear solution for fine-grained control over sorting and paging your results via query strings - the common practice for RESTful APIs. This creates a lot of development overhead for headless and API intensive sites which will inevitably end up with innumerable views.

Creating publicly available APIs would be worse yet. Typically, you would like a public API to allow your consumers to discover and access your data as they see fit. Managing each view for all your entity types becomes increasingly difficult with every new field added or new entity type. This issue makes sense, the Views module’s original intent was to provide prescribed aggregations of your content, possibly modified by a few contextual items like the current path or the current user. Views were never intended to be an all-purpose query tool for the end user.

Enter Entity Query API. Entity Query API allows API consumers to make queries against any entity in Drupal. From users, to nodes, to configuration entities, this is an incredibly powerful tool. By creating a standardized set of parameters for crafting these queries, Entity Query API allows developers to create generalized tooling not tied to particular views or entities. Moreover, they need not worry about creating matching views for every collection of content. This ability to let API consumers craft their own result-set further reinforces the separation of concerns between the client and the server.

Entity Query API does all this by taking advantage of the excellent QueryInterface provided by Drupal Core. The module simply translates your request URI and associated query string into an entity query on the backend, executes it, and returns the results as JSON. By using this, we also get the built in access control that Drupal entity queries provide.

Entity Query API is still in alpha (as of April 2016), but it fully supports everything that you can do with an entity query in code, i.e., conditions, condition groups, sorting, ranges, etc. Like the REST UI module, we have a similar configuration page for enabling queryable entities. We support all core authentication methods as well as JSON Web Token Authentication (another module we’ve built). In future, we’d like to dynamically collect any authentication providers available, just like the REST UI module.

I’m going to be sprinting on Entity Query API at DrupalCon New Orleans on Monday, May 9th 2016 and during the after-DrupalCon sprints on Friday, May 13th 2016. We’d like to add support for other encodings like XML and HAL+JSON (currently the module just supports JSON). Finally, we’d like to add the option to retrieve just entity IDs instead of fully loaded entities.

As always, there’s plenty of work to be done in open source. If you’re interested in Entity Query API, come find me during the sprints or send me a tweet anytime during DrupalCon, my handle is @gabesullice. Of course, the easiest way to help is just to download the module and report any bugs you find. Finally, if you're going to be at DrupalCon New Orleans, stop by the Aten booth, I'd love to hear your ideas and feedback!