Learning GraphQL

GraphQL is a query language created by Facebook in 2012 to provide a common interface between clients and servers by defining their data capabilities and requirements.

While GraphQL is commonly thought of as an API technology for frontend applications (especially Relay), it’s generally applicable.

Example

Here’s an example GraphQL query document that you might send to a server to query for specific user information:

{
  user(id: 123) {
    first_name
    last_name
    avatar_url(size: "thumb")
    friends(limit: 3) {
      first_name
    }
  }
}

Provided that the server’s GraphQL schema supported the fields you’ve requested, you’d get back exactly what you want:

{
  "data": {
    "user": {
      "first_name": "Jane",
      "last_name": "Avery",
      "avatar_url": "http://example.absinthe-graphql.org/img/users/123-thumb.jpg",
      "friends": [
        {"first_name": "John"},
        {"first_name": "Jack"},
        {"first_name": "Jill"},
      ]
    }
  }
}

If we requested fields that weren’t supported by the schema defined on the server, forgot required arguments, or passed arguments that were invalid, the server would let us know via helpful error messages, all without manual, custom-written intervention by the schema writer.

Plus, the schema can be introspected by clients.

Resources

Here are some resources that you may find useful. Just keep in mind you’ll be writing Elixir, not JavaScript!

Specification

The current version of the specification is the October 2016 Working Draft.