GraphQL

1 March 2018

What is GraphQL?

GraphQL is a specification for a query language for APIs.

It is an alternative to REST.

Who uses GraphQL?

GraphQL is in use by many notable companies, including

(if you care)

Why GraphQL?

Specificity

We can request only those fields we will use

Predictability

The response format matches the the query

Efficiency

We can get more than one thing at a time

Discoverability

We can ask a GraphQL schema about itself

This is a publically-available web app that you can use to run GraphQL queries against GitHub's GraphQL API. Let's open the Docs pane. Here you can see that the schema supports query and mutation types. Let's see what kind of queries they support. There are quite a few! Let's explore Licenses. We can see that there is a license field that takes a key. We'll try "MIT." Cool. Now suppose we didn't know what license keys exist. But we see there is a licenses field, and we can introspect to find keys. What else can we learn about licenses? Let's look at limitations. Notice that the editor automatically filled in some fields for us! All of this can happen because the schema can be introspected, allowing the tool to give us things like searchable documentation, auto-complete, and query validation.

Reliability

We can stop versioning our API

GraphQL takes a strong opinion on avoiding versioning by providing the tools for the continuous evolution of a GraphQL schema.

Most APIs version because when there's limited control over the data that's returned from an API endpoint, any change can be considered a breaking change, and breaking changes require a new version. If adding new features to an API requires a new version, then a tradeoff emerges between releasing often and having many incremental versions versus the understandability and maintainability of the API.

In contrast, GraphQL only returns the data that's explicitly requested, so new capabilities can be added via new types and new fields on those types without creating a breaking change. This has lead to a common practice of always avoiding breaking changes and serving a versionless API.

Tools

graphql-ruby

A gem by Robert Mosolgo of GitHub which provides a GraphQL server implementation and a DSL for defining your schema.

rmosolgo/graphql-ruby

Basic graphql-ruby usage

In practice, broken out into classes

N.B. this syntax is in flux

A client-side library for React, iOS, and Android
A mock server to develop front-end code against
From Meteor Development Group

Basic Apollo usage example

GraphiQL

Provided by graphiql-rails gem, runs independently, also available as an Electron app

Summary

GraphQL is a spec for building an API
Advantages are specificity, predictability, efficiency, discoverability, and reliability
Back-end, front-end, and introspection tooling is available

The End

GraphQL definition from graphql.org, BSD 3-Clause
https://developer.github.com/v4/explorer
https://www.apollographql.com
https://github.com/rmosolgo/graphql-ruby
http://facebook.github.io/graphql/October2016
https://github.com/benkimball/graphql-primer