Introduction to GraphQL for Drupal Developers

Submitted by dryer on Sat, 06/18/2016 - 11:10
GraphQL simple logo

GraphQL is a high level communication protocol that can be used as an alternative to REST APIs. Ever since the keynote DrupalCon 2015 in Barcelona the interest in GraphQL has increased in the Drupal community. GraphQL is a great match for Drupal as the use of Drupal as a headless CMS continues to rise.

One of the biggest advantages of GraphQL over REST APIs is that it's a complete specification. This means that even though the GraphQL was only officially published in 2015, it is already widely supported by different persistence options such as complete GraphQL powered BaaS like Reindex to database level implementations like postgraphql.

Instead of developers creating their own Drupal REST API specific applications, developers can use common tools from the JavaScript world using a GraphQL abstraction layer like Apollo to abstract between Angular 2 and React.js. So while GraphQL originates from Facebook, it's very much a technology that's usable everywhere.

The whole GraphQL specification is built on the following core principles:

  • GraphQL is hierarchical: Everything in GraphQL is represented as a hierarchy of items.
  • GraphQL is product-centric: GraphQL is built based on real needs and not a technical theory
  • In GraphQL the client specifies the queries: The consumer of the API defines the shape the responses are returned in.
  • GraphQL is Backwards compatible: In an API driven world it's important to maintain backwards compatibility. GraphQL does this transparently and there are no versions of a GraphQL API.
  • In GraphQL all queries are Structured: The query language in GraphQL is highly granular, but as the client defines what it returns it means results are optimal compared to a generic API
  • GraphQL is a high level protocol: As an application protocol GraphQL is designed to be usable with any lower level protocol, rather than being tied to HTTP like REST is.
  • GraphQL is strongly typed: All entities exposed through a GraphQL compatible API must define their type. This makes it easier to validate and consume an API when you know price for example is an actual floating point value and not text, for example. 
  • GraphQL is introspective: For REST APIs the documentation is largely dependent on who is creating the API. With GraphQL the definition and the type system itself can be used to automatically create the documentation when necessary.

State of GraphQL in Drupal

For Drupal developers the natural way to take GraphQL into use is the GraphQL module. This endeavour backed by Dries Buytaert's Acquia company and developed by Sebastian Siemssen of Amazee labs. This module enables developers to view the Drupal internal data model through a GraphQL interface.

The module itself automatically generates a GraphQL schema using the internal Drupal API for TypedData. This enables developers working with rich front end applications build with Angular or React.js. Just as well a centralized enterprise Drupal content repository can hold the master data and this can be used to create simple sites with Metalsmith, for example.

Currently there are known limitations in compatibility with Relay as well as partial support for exposing configuration entity types. Also currently GraphQL with Drupal is only read only as GraphQL mutations are not currently supported by the module. While complete Relay support is not there, it means that you will simply not get access to all functionalities like automatic data pagination and more.

In a recent article the module developers gave a view to what is next for the GraphQL module in Drupal:

  • Read support for all content entity types, all their fields and all properties of each possible field type.
  • Read support for various other data types that are currently defined as typed data definitions (e.g. Languages).
  • Query support for all queryable fields through EntityQuery.
  • Query support based on configured Views for complex scenarios where you need a special entry point that exceeds the capabilities of EntityQuery.
  • Query support for Views based on contextual filters that can be resolved through any of the entity types for which we are generating the schema. This will allow you to create a View with a contextual filter of type “user” and then have it automatically appear as a traversable reference in the user schema.
  • Following references of any data reference type specified through typed data (e.g. entity reference fields).
  • Reverse querying of entity reference fields (e.g. fetching all nodes that reference a particular user entity by following the “uid” entity reference field in reverse).
  • Entity and field level access checks based on the Entity and Field Access API.
  • Manual aliasing of field names to mask some of the uglier machine readable names.
  • Extendability through custom type resolvers.
  • Graphical interface for crafting queries and exploring the schema by integrating GraphiQL