Introduced in 2012 by Facebook and publicly released 2 years ago in 2015, GraphQL is getting very popular. So what is GraphQL exactly? And what is this technology really solving?

First thing you need to know is GraphQL is a Data Query Language, it’s an alternative to REST API’s and it’s really really cool!

The problem Facebook faced at the time they created this service was coming from their news feed. Indeed, in the Facebook newsfeed you can have a list of POSTS created by AUTHORS. For each one of these POSTS you might have COMMENTS created by other AUTHORS or FRIENDS, then you can have LIKES on these COMMENTS. Each POST can embed an EVENT that has PARTICIPANTS, etc..

As you can see there is a lot of nested resources: POST, COMMENT, AUTHOR (USER), PARTICIPANT (USER), FRIEND (USER), EVENT, LIKE, …

The difficulty with this scenario is that REST APIs are resources based. So if you want a resource or a list of resources, you need to perform a new API call for each of them. In this case, you would have the following:

  • GET /users/1234/feed -> list of posts
  • GET /posts/1234/comments -> list of comments for the post
  • GET /comments/<a…z> -> comment details (authors, likes, reply, …)
  • GET /post/1234/event -> event details
  • GET/event/2345/participants -> list of users participating

As you can see REST is not adapted for this kind of application. The solution Facebook had was to create a graph request, defining any nested resources they need to access several pieces of information in one single call! What was left to do was to configure a service that would handle the graph request, validate it, execute it and return the expected response.

The graphQL service has to define a Query that exposes Types (that can be a resource or a simple type such as string) and for each Type we can declare fields. Then you can request your data like this:

{
  me {
    name
  }
}

And you’ll get the following response:

{
  "me": {
    "name": "Luke Skywalker"
  }
}

Looking at this JSON response it’s clear that it’s very close to a REST response. The service simply defines what Type of resource you can request, what are the fields (and their types) available for each resource, and obviously how to fetch each resource.

GraphQL is not tied to any storage engine or database, you can set it up using your existing code, just exposing this service as a new endpoint.

There is some really cool stuff coming with GraphQL for free such as validation. For example when the client sends a query to the service, before the service is even processing it, it will check that the data requested is valid based on the types that have been pre-defined in the service. It means that your server will not even try to execute this request, it will directly return a validation error to the client.

Another benefit is dynamic models. Using Fragments for instance, the client can decide how he wants to get the data back from the service which means no need to support the model data structure on the server. How many times do you have to create a new v2, v3, etc endpoint because your resources changed, or because you have to expose new available resources? And of course, this also implies to update any clients that are using your API, to make sure they are consuming the correct version, parsing the response as expected, etc…

So what’s next?  TRY IT! Below is a list of resources can assist

Here is a list of resources to help you getting started: