GraphQL for Drupalers - the basics

GraphQL is becoming more and more popular every day. Now that we have a beta release of the GraphQL module (mainly sponsored and developed by Amazee Labs) it's easy to turn Drupal into a first-class GraphQL server. This is the new GraphQL series in which we'll describe the features that are new in beta and provide a detailed overview of the integration with Drupal's entity and field systems.

GraphQl for Drupal

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.

GraphiQL initial screen.

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.

Root query in document explorer

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:

userById field signature

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:

Document explorer user name

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.

Tags field in GraphQL Voyager

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

 

November 9, 2017
3 Comments

Get our Newsletter

Comments

Ran composer install in the module directory and it installed Youshido under vendor but I still get the following error when trying to install in Drupal. "youshido/graphql component not found"

By Chip
3 days ago

Hey Chip,

Composer commands should be fired in the project root, where the main composer.json file is. If you're using the drupal composer project template as a base, it should be one level above the document root or otherwise in docroot. Try running `composer require drupal/graphql` there. If that doesn't help please don't hesitate to drop us a line in the #graphql channel in drupal slack (https://drupal.slack.com/).

By Błażej Owczarczyk
3 days ago

Thanks very much Błażej! It's working now, was just running composer from wrong location.

By Chip
2 days ago

Add new comment

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.
icon
What is Amazee Labs?