GraphQL for Drupalers - part 1 - the basics

This is the new GraphQL series about the new features that are in beta (published 2 weeks ago) and how they are connected with Drupal out of the box

The modules

Let's start with the modules we need. Recently there were quite a few changes in this field. In alpha we had:

• graphql - The main module laying the foundations for exposing data using Drupal plugins.
• graphql_core - which exposed Drupal core data - the info about entity types and bundles, but not fields
• graphql_content - which handled field exposition with the view modes
• other auxiliary modules (e.g., graphql_boolean graphql_entity_reference) that provided behaviours for specific field types

In beta, the structure has changed. Now the default schema exposes all the Drupal fields and (content) entities in raw form, using the typed data. Thanks to that GraphQL became a zero-configuration plug and play module. We just need to enable graphql and graphql_core (the only two modules that are shipped with the package now) and we're good to go.

NOTE: The other modules are still available in case you need them, they're just not part of the core package anymore. graphql_legacy is where most of the field modules went. Besides that, there are graphql_views  which lets us expose views, the promising graphql_twig that allows using GraphQL queries without a decoupled setup and a few more. All of the modules are listed in the drupal-graphql organization page on GitHub.

The Explorer

After enabling graphql and graphql_core we can go ahead and test it with GraphiQL; an interactive tool that lets you run queries, see results in real time and preview all the available fields along with arguments and return types. It also provides query validation, autocompletes suggestions and keyboard shortcuts. Thus, it's a kind of an IDE. The explorer is connected with the schema. We can find it next to the Default Schema under: Configuration -> Web services -> GraphQL -> Schemas or using the direct path - graphql/explorer.

This is how it looks. On the left, there is a query box with a comment describing the tool and listing the keyboard shortcuts. Results show up in the box on the right. To run the query we can use the «play» button at the top, or the keyboard shortcut (Ctrl-Enter). One more important piece is the < Docs button in the upper right corner. This is where we can see all the available elements. Let's go ahead and click it.

The only thing we can start with is the query field which is of type RootQuery. Clicking on the type shows a list of available sub-fields, including userById, which looks like this:

This field takes two arguments: an id (which is a string) and a language (which can be set to any language enabled on the site) and is of type User. Clicking on the type brings up a list of fields on a user. The name is a string:

Strings are scalars (which means they don't have subfields) so we can finish our simple query here. It will look like this:

and (after running it with Ctrl-enter) the response is what we'd expect

The GraphQL explorer (or GraphiQL) gives us the ability to easily write and debug every GraphQL query. That's a feature that's hard to overestimate so getting familiar with it is a good starting point to understanding how GraphQL works in general and how we can get our Drupal data out of it.

The Voyager

Voyager is another schema introspection tool, a visual one this time. It draws a chart of all the types and field in the system and presents it in a nice way. It can be found next to The Explorer under: Configuration -> Web services -> GraphQL -> Schemas or using the direct path - graphql/voyager.

That's it for this post. In the next one, we'll see some examples of retrieving data from Drupal fields.

Other posts in the series

• GraphQL for Drupalers - part 2 - the queries
• GraphQL for Drupalers - part 3 - the fields