Share: Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInShare on RedditEmail this to someonePrint this page


GraphQL is a data query language and runtime that allows client applications to specify exactly the data they need.


GraphQL Overview by Jonathan Kaufman

Hassle free slidedeck hosting. Designed from the ground up for technical presentations and the need of our community!


Before we really understand what that means, let’s imagine we’re building a large scale application using RESTful APIs. In this example, we’ll be creating a “user page” for our hypothetical (albeit, awesome) app. Seems simple enough; we’ll create some kind of /user endpoint on our server, maybe it’ll take a userID parameter, and we’ll be good to go:

A few months later, our app has become very successful! Yay! In the interim,
we’ve built several versions of a mobile app on iOS and on Android as well as
have iterated a ton on our web app. This is all well and dandy, but has resulted
in the following endpoints:


Because each version of our mobile app and our web app are requesting slightly different information to render the user page, we are left with a nightmare to maintain. There’s this difficult balancing act we have between supporting different versions of our API for each app update, or having our clients over or under fetch data. Overfetching is no good if our users have poor internet connections, and underfetching is no good because it prevents our client applications from rendering everything they want.

graphQL to the rescue!

The idea with GraphQL is to have the client express the exact data they need to render their app, and have the server return just that. Let’s look at an example. Sending off the following query:

would return the following response:

If we no longer wanted to return the id or the profile picture, we would instead issue this query:

and in turn get this response:

We can immediately see the benefits of GraphQL:

  1. Queries are shapes exactly like the data they return.
  2. The specifications for queries are maintained by the client applications
    requesting the data, rather than the server. This returns exactly what a
    client asks for and no more.

GraphQL even provides us with a syntax for creating composable queries:


setting it up

GraphQL was designed to be as thin a layer as possible between your data and the client request. To this end, all you really need to do is set up a schema. To do this, you use Facebook’s tools to define complex object types:

and then piece it together in a schema object that maps from type –> data:

The resolve function does most of the heavy lifting here. Once your function’s arguments are set up, the resolve function can do whatever it needs to do to get the data. It can go off to a database, retrieve the data from a cache, etc.

Because everything in the schema is stongly typed, the server can make certain guarantees about the response.

If you’re using the express framework, to set up your endpoint, you simply:

It’s important to note that when Facebook open sourced GraphQL they first only open sourced the spec and a reference implementation. The spec was incredibly thorough and allowed third party developers to create GraphQL in any langauge they pleased. Because of this, you’re not stuck

not covered

To keep this post as short as possible (while still demonstrating the power of GraphQL), the following topics were not covered (but know that they’re possible):

  • Mutations
  • Optimistic Updates
  • Deletions
  • Introspection
  • Caching
  • Rolling up Queries

more resources

This post was intended to get y’all excited about GraphQL and consider using it in your next project, not to be a one-stop-shop to become a GraphQL expert. Here are some good resources for you to continue your journey to server-side-awesomeness:

  • Official Docs: the documentation and getting started guide in Facebook’s official docs are quite powerful. They walk you through use cases and have you set up a mock server.
  • Awesome List: this “awesome list” points to different implementations of GraphQL (everything from JS to Lua) as well as different client-side frameworks for composing your queries.
  • GraphiQL: GraphiQL is an in-browser IDE that allows you to query your GraphQL server in real time and perform introspection into the schema.
Share: Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInShare on RedditEmail this to someonePrint this page
Jon Kaufman

Jon Kaufman

Developer Advocate at IBM
Jon Kaufman
Jon Kaufman

Latest posts by Jon Kaufman (see all)

Jon Kaufman

Leave a Reply