What is GraphQL?

If you’ve followed the Meteor community recently you might have stumbled upon different blog posts and discussions about GraphQL, a new kid on the block in Meteor development.

But what is GraphQL? Why do I need it? This blog post will explain to you what GraphQL is and how it works.

The history of GraphQL

GraphQL was initially developed at Facebook as a new way to deal with the problems which came up due to the rapid development of the Facebook platform.

Fronend and Backend teams had to define a way they can agree upon what data can be served and is available to consume. Traditional REST style APIs were not sufficient enough and broke the Facebook codebase too often.

Here’s a simple example

Let’s say the fronted team adds a new feature, where the username is shown next to the users real name.
Additionally the five first comments are shown when the user hovers over the newly added username attribute.

Back in the REST API days, the backend team had to (re)define the response for the API that delivers the users information. A username field has to be added to the response.
The next thing which needs to be added is a new REST API endpoint which delivers all the necessary comments for that one specific user.

You may see that this is not a scalable solution (notably not for Facebook). You need to specify each and every field / endpoint in the REST API. The above example may also lead to multiple roundtrips (first fetch the user via an API call and then get all the comments for that specific user in another API call) to the server.

The guys at Facebook thought about a better solution and developed GraphQL.

How GraphQL works

GraphQL is a thin layer between the fronted (your app) and the backend which delivers your data. It defines a common interface between the server and the client to ask for and retrieve data.

With GraphQL the client describes what he needs to display. In the old days the server described what’s available to consume by the client.

Let’s look at a simple GraphQL query to see that this is no magic:

user(id: 123456) {<br />
  id<br />
  name<br />
  username<br />
  comments(first: 5) {<br />
    title<br />
    body<br />
  }<br />
}<br />

I bet you could read the code and understood it nearly instantly.

This code fetches the id, name and username of the user with the id 123456.
Additionally the first 5 comments (the title and body attributes of the comment) are delivered as well.

It’s very easy for a fronted developer to modify this query:

user(id: 123456) {<br />
  id<br />
  name<br />
  username<br />
  friendCount<br />
  comments(first: 5) {<br />
    title<br />
    body<br />
  }<br />
  likes(first: 10) {<br />
    id<br />
  }<br />
}<br />

No need to write code to warp the parameters and interact with the REST API or unnecessary roundtrips to fetch related data.

Note: GraphQL is just a specification. The reference implementation is done in JavaScript. You can implement your own GraphQL implementation in any language you like.

Learning resources

This sounds great and you want to learn more? There’s a great tutorial available which was made by the guys from Kadira. It’s a very concise introduction to GraphQL. So Just head over the tutorial and give it a spin.

Conclusion

GraphQL is a very new and nice approach to define what data is available via an API.
It especially useful when you have many moving parts in your application and want a way which is easy for fronted developers to interact with the data you have available on the server.
The Meteor community discussed this new technology and partially already embraces it. The future will show if GraphQL is adopted and may replace REST APIs as a go to standard for data exchange between client and server.

Additional resources

• http://graphql.org
• https://code.facebook.com/posts/1691455094417024/graphql-a-data-query-language/
• https://learngraphql.com
• https://kadira.io/blog/graphql/why-we-built-the-learn-graphql-project
• https://kadira.io/blog/graphql/initial-impression-on-relay-and-graphql
• https://compose.io/articles/using-graphql-with-mongodb/
• https://github.com/kadirahq/meteor-graphql