March 4, 2016

Intro to GraphQL

Jonas Helfer

Jonas Helfer

GraphQL is Facebook’s new query language for fetching application data in a uniform way.

If you’re a Javascript developer, chances are that you’ve heard of GraphQL, but you’re not quite sure what exactly it’s good for, and whether it’s more than just a hype. To help you out, I wrote this short guide to the best articles, videos and tutorials for figuring out GraphQL.

By the end of this guide, you’ll be able to answer the following questions:

  1. What is GraphQL?
  2. Why are people so excited about GraphQL?
  3. How can GraphQL make my life better?

You can read the links in this guide in any order you like, but if you’re not yet familiar with GraphQL, I recommend starting with the first one.

Alright then, let’s get started!


1. Read Facebook’s GraphQL Intro

This excellent article written by Nick Schrock explains Facebook’s motivation behind creating GraphQL. If this is the first thing you’re reading, skip the part about Relay and go straight to the section on GraphQL. There’s a lot of information there to process, but the most important takeaways are:

  • GraphQL was designed to solve of the biggest drawbacks of REST-like APIs. You should think of GraphQL as a better alternative to REST.
  • GraphQL is not a database query language like SQL, it’s an application layer query language that you can use with any backend — SQL, MongoDB, Redis, etc.

2. Watch Exploring GraphQL from React Europe

In this video, Lee Byron covers some of the same ground as the GraphQL Introduction, but goes into more detail about the query language. If you don’t want to hear about the motivation behind inventing GraphQL again, skip right ahead to 6:01 to learn about how GraphQL queries are structured.

Apart from the fact that GraphQL has a beautifully simple structure, there are two things that I think are worth emphasizing:

  1. GraphQL’s type system enables amazing features that we all wish REST APIs had, such as introspection, on top of which we can build tools like GraphiQL that let you quickly explore the capabilities of a GraphQL endpoint. If you want to watch that part again, it starts at 10:24.
  2. GraphQL doesn’t require you to rewrite your current backend. In fact, it’s quite the opposite. You can use GraphQL with your existing backend, while making your API simpler! Don’t believe it? Watch it again, it’s at 19:14.

3. Try it out yourself: build a simple GraphQL server

Now that you have an idea what GraphQL is, it’s time to get your hands dirty! That means you’ll have to write your first schema, which can be a bit confusing. But don’t worry about it for now, because Clay Allsopp’s post walks you through creating the schema, writing the queries and even calling mutations, and you’ll see it’s all quite straight forward!

If you get stuck with Babel — you probably will — take a look at this comment, which explains what you need to do to get it to work with Babel 6.

The main takeaway here is that a GraphQL server is not difficult to set up. Getting Babel 6 to work is probably the most difficult part about it!

4. Learn GraphQL properly to see how awesome it is!

Learn GraphQL by Arunoda Susiripala is an excellent 10-part tutorial that teaches you the basics of GraphQL. It requires you to log in with your github account to get all the content, but it’s definitely worth it, because it’s hands down the best way to learn GraphQL at the moment.

It’s worth noting that parts 1 to 6 are are about writing GraphQL queries, which are defined by the GraphQL spec, but parts 7 through 10 are about express-graphql, an implementation of a GraphQL server in Javascript. That means that schemas for other GraphQL servers have to be written in a different way!

5. Go for a deeper dive and read “From REST to GraphQL

This excellent post by Jacob Gillespie covers some of the interesting things he learned when converting a REST API to GraphQL.

The first part talks about the many reasons why REST didn’t cut it any more. If you’ve followed all the links until here, these probably come as no surprise to you, but it’s always more enlightening to read a first-hand account.

The second part contains a lot of very useful insights about GraphQL, many of which you don’t find anywhere else. It answers some of the most common questions that people usually have about GraphQL. Some of the “Future Puzzles” Jacob mentions, such as client side caching and Realtime updates are actually things we at Meteor are trying to tackle together with the community through project Apollo.


That’s it for now. What do you think about GraphQL now? Have you already used it or would you like to try it out? Have something to add or correct? Let me know in the comments!

In any case, stay tuned for more posts by Sashko Stubailo and myself in the coming weeks as we learn more about GraphQL together!

Written by

Jonas Helfer

Jonas Helfer

Read more by Jonas Helfer