Drupal and GraphQL - Batteries included

More than data

After being educated by more than a decade of thinking in terms of RESTfulness and pure data, the solution seems obvious. Drupal 8 has Typed Data and therefore we know everything about our data structure and can just automatically generate GraphQL types, fields and interfaces from it. Awesome, we’re done!

Well you only need the light when it's burning low
Only miss the sun when it starts to snow
Only know you love her when you let her go

I suspect that Michael David Rosenberg was trying to build a decoupled Drupal website, gave up and wrote this song instead. The moment you reduce Drupal to a pure object database you will learn what else it does for you. How did you plan to handle ...

• Output filtering and XSS protection
• Routing and Redirecting
• Arbitrary Listings
• Image processing
• Menus and Breadcrumbs
• Blocks
• Translations
• The editable and context sensitive “Contact” block in the footer …?

And that’s just what ships with Core. Obviously, you can build that all into your frontend application, but that’s a lot of development time spent on implementing things that have already been tested and are there for you to use.
As stated in the first post in this series, GraphQL is an application level query language, which means data and operations are equally important. Actually, this brings it rather close to SOAP. This might send shivers down some spines, but stay with me - we learned from the lessons of the past and gained some valuable insights.

Submodule overview

After experiencing some painful “Aha”-moments, we started to implement a GraphQL Schema that allows us to tap into very different levels and areas of Drupal’s feature-set instead of typed data alone. This growing collection of types and fields has been split up into submodules that can be enabled on demand. Let’s have a look at them, one by one.

GraphQL Core

The base module all others depend on. It introduces a system of overridable plugins (Fields, Scalars, Types, Interfaces, Enumerations and Input Types) that are automatically assembled to form our GraphQL Schema. In addition to that, it includes plugins that expose some basic Drupal mechanisms: Routing, Context and Entities.

For every entity type, there is a corresponding query field that makes it possible to run property-filtered queries and will return a list of entity objects that contain the UUID. This might not seem very helpful, but more on this later.

More interesting, however, is the route field. It takes a path as an argument and returns an object of type Url which contains fields for every defined context in Drupal. This way it’s possible to pull the content language, current user or node for a given path. Any context provided by a contrib module will also be picked up automatically.

GraphQL Content

As mentioned above, the entity objects returned by entity queries and contexts only contain the UUID, and are therefore not terribly useful. That’s where the second base module takes to the stage. In the last blog post, we already used it to configure a view mode and defined the fields that are exposed to the GraphQL API. Let’s have a closer look what happened there.

The module will pick up all enabled content entity types and bundles and transform them into corresponding GraphQL interfaces and types with fields for common entity properties. If a view mode has been assigned, the configured fields will be attached to the GraphQL type. The fields will return string values rendered according to their field formatter configuration. This means we keep input filters on our body field and all other field formatters that are out there as well.

The latter is what happens by default. It is, however, possible to define special field formatters that alter this behaviour and return custom GraphQL types. One example is the built-in "GraphQL Raw value" formatter, which returns Typed Data objects. By that, we successfully closed the circle and are able to get back to raw, unprocessed data values when necessary.

A bunch of modules in the repository do something similar to “GraphQL Raw value”, but with a different spin for the corresponding field type. Below is a brief rundown on each module’s purpose:

GraphQL Boolean

Provides a GraphQL Boolean formatter that will make sure that the response value is an actual boolean and not a string. As simple as that.

GraphQL File

Turns file fields into objects containing useful file information like mime type, file size and the absolute file URL for downloading it.

GraphQL Image

One of the more important ones. Image fields will return types that contain “derivative” fields that allow us to pull information about specific image styles. This also makes it easily possible to grab multiple image styles at once.

GraphQL Entity Reference

Instead of returning the rendered entity or the raw target_id value, this allows us to traverse the entity relation and query the related type. The result type will again expose fields based on it’s configured view mode for the entity type retrieved.

GraphQL Link

Exposes the link field title, attributes and URL. So far so “raw value”. But there’s  a catch! The URL field is not a simple string, but an object of type Url.

Remember, the one also returned by the route field with all defined contexts attached? It is possible to pull contextual information for any path inserted into a link field. But beware: this will issue a kernel sub-request, which will have a performance impact when overdoing it. Not sayin’ it’s a good idea, just sayin’ it’s there.

GraphQL Content mutation

Adds GraphQL mutations for all content entities, which means it enables you to write any content data out of the box -provided the user has required permissions since this and all other entity features will respect entity access.

GraphQL Block

This module adds a blocksByRegion field to Url objects, which will retrieve block entities displayed in this region. Access conditions will be evaluated against the Url object’s path and the default theme. Until configuration entities are fully supported, this field has limited use on its own.

However, when used in combination with “GraphQL Content”, returned Content Blocks contain the configured fields just as nodes do. This way we maintain the ability to inject blocks of meta-information that are configurable from the Drupal backend and even respect any visibility settings and contexts.

GraphQL Menu

This module provides us with a root level field for querying menu trees. The structure returned will respect access permissions but it does not mark active states. This is done in the client implementation when necessary so we don’t have to re-fetch the whole menu tree on every location update.

GraphQL Breadcrumbs

Retrieve a list of breadcrumb links from any URL object.

GraphQL Views

Last but not least, there is the views integration. One of the most versatile tools in Drupal is also a must have in your decoupled application. We already used it in the last instalment of this series to create the listing of posts, so we can skip boring examples and get to the juicy theory right away!

Any “GraphQL” views display will provide a field that will adapt to the views configuration:

• The fields name will be composed of the views and displays machine names or configured manually.
• If the view is configured with pagination, the field will accept pager arguments and return the result list and count field instead of the entity list directly.
• Any exposed filters will be added to the “filters” input type that can be used to pass filter values into the view.
• Any contextual filters will be added to the “contextual_filters” input type.
• If a contextual filters validation criteria match an existing GraphQL type, the field will be added to this type too, and the value will be populated from the current result context.
  TL;DR: We are able to create a view that takes a node as context argument and the field will be added to all GraphQL node objects.

Future Features & Lookout

That’s a wrap! We covered all features that help you to build an automated schema included in the GraphQL module at the time of writing. There a lot going on and the community is working hard to implement improvements like:

• Support for views field displays.
• Partial query caching.
• A dedicated user interface for graph configuration.
• Mutations based on actions and rules.
• Performance optimization with deferred resolving and lookaheads.

In the next blog post we will take a look at the underlying API and show how you can use it to extend the schema with custom functionality and - even more important - contribute and help to make these features come alive!