First adventures in GraphQL

Submitted by mrjmd on Wed, 05/18/2016 - 07:10

Last week at DrupalCon New Orleans I attended the session by Sebastian Siemssen on GraphQL and Drupal (recording here). GraphQL first hit my radar when I came across a talk at last year's NYC Camp about it by Preston So, and I've been excited about its potential and mentioning it when I speak ever since. So I was eager to finally see it in action working with Drupal, and even more pumped to get it up and running on my own machine so I could play with it myself.

Sebastian's session was excellent and covered a lot of the exciting features already in the module as well as where the gaps were, but unfortunately by the end I still didn't fully understand how to make Drupal and GraphQL work together. I could see it working on his machine but had no idea how to make it work on mine. He emphasized though that he was looking for help and was planning a BOF for the next day to dive into the details. I gave him my card after the session was over and he let me know when and where the ad-hoc BOF was going to be.

There were four of us in the BOF, which we held in the sprint room since all the actual BOF rooms were taken. We announced "GraphQL BOF" beforehand and one other guy came over, asking what GraphQL was and what kinds of graphs you could make with it. We explained that's not quite how it worked.

For those of you who don't know, and can't be bothered to watch the excellent videos above, I'll try to be brief - GraphQL is a query specification created by Facebook, one that allows declarative querying of a single endpoint. If you've worked with decoupled sites lately you know the typical way backend data is retrieved by the client side, through RESTful endpoints usually formatted as JSON. This approach can work really well under the right circumstances, when the back and front end teams are communicating effectively (or are the same person), endpoints can be created exactly as and when needed, with the structure that the client side application requires.

However, there are a few problems that can arise from this approach:

  • On large sites, you can end up with a LOT of endpoints. Unless they are self-documenting (that's a joke) or the front end team is familiar with how to find and use them, having dozens or even hundreds of different endpoints with variations on types and structures of data can quickly become very confusing.
  • When a new piece of front end functionality is needed, a new endpoint may be needed, necessitating two different teams to do work and creating unnecessary cycles. Or, even worse, a front end developer may just decide to use an existing endpoint that already provides more than enough data and iterate through it for their specific needs, or use a combination of endpoints to get the data they need leading to multiple requests.

GraphQL  solves these issues, by letting the client request data, specifying the exact type and format they desire as part of the request itself. Then GraphQL simply fills in the request and sends it back. This means that a single endpoint can be powerful enough to serve all of the data of your backend site out.

Before I show an example though, let's go through how to spin up a GraphQL server on your own local Drupal 8 box and try it out yourself. First things first, you will need a Drupal 8 site up and running, as well as composer installed. Once you've got that ready, it is really only a couple of commands that you need to run. But they must be run from the docroot of your Drupal site.

// This will add a new repository to your composer config.
$ composer config repositories.drupal composer
// Then install the module as well as the PHP library all at once.
$ composer require drupal/graphql 8.x-2.x-dev

After that, turn on the GraphQL module in Drupal as usual, and you should be ready to rock. Navigate over to /graphql/explorer to test out your GraphQL server with a basic query (query is on the left, response on the right):

Basic GraphQL Query

I'll be working with Sebastian to document out more of what is possible in the coming weeks... but to take the next step towards using it in your actual applications, I recommend experimenting with queries in the explorer like above, and then opening the network tab of your debugger and looking at what the actual request sent to the endpoint looks like.

Add new comment

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.