Dive into GraphQL

Iván Corrales Solera
5 min readJan 23, 2019

Material used by myself to do an introductory workshop on GraphQL

Dive into GraphQL

How many times do you find API’s that re not well documented?

How many time you don’t agree with your workmates about the HTTP status?

How many times do you disagree with the chosen endpoint for a REST Service?

What’s GraphQL?

GraphQL is not a programming language, nor a a framework. GraphQL is just a specification that tells how we must implement our API’s

GraphQL is focused on API’s consumers, being the clients the ones who decide with data want bring from the server side.

Who invented GraphQL

GraphQL was invented by an engineering team at Facebook by 2012.

GraphQL was announced in 2015 and It’s currently maintained by the open source community.

Facebook site

Having a look at Facebook we find that a lot of information is showed in any page.

User details, family details, list of friends, working experience… Thinking of REST, this would imply several services requests….

Who’s using GraphQL

Since GraphQL was published several companies have been adopting this specification in order to implement their own services.

Some of the most known companies are the ones in the picture.

Awesome this article written by Mark Stuart (Lead at Paypal)

Resto vs GraphQL

A good way to understand GraphQL can be comparing it to REST.

GraphQL provides a single endpoint

REST provides an endpoint per each implemented service. Since Rest is implemented over HTTP protocol we need decide not only the endpoint but also the verb for our service.

GraphQL provides a single endpoint (usually /graphql) and all the services can be consumed pointing to this endpoint.

GraphQL is typed

GraphQL is typed. This means that both, client & server known which information is sent. Even most importante the fact that we also know the type of the data.

GraphQL establishes a contract between client & server that makes communications easy.

GraphQL is not a versioned API

Do you agree with your workmates when the API needs to be upgraded to a new version?

Versioned API is a .common practice in REST but GraphQL doesn’t bet for it. GraphQL proposes that API mustn’t be versioned. However, it provides mechanisms to deprecate old or unused data from our API’s

GraphQL is focused on API’s client

GraphQL is highly focused on making the life easier to the clients. The clients can always decided which data want to retrieve from the server.

However, in REST architectures this decision is taken by the server.

Error handling

Again, as REST is coupled to HTTP protocol, it makes use of HTTP statuses in order to represent an error:

All GrahpQL responses will be a 200OK even when something failed. Error is defined inside the response body


Cache is implemented in HTTP protocol, so REST take advantage of this.

GraphQL cache doesn’t implement a cache mechanism so must be the client the one that decided how their data are cached. (In future posts I will explain how we can do it)

GraphQL secured

An amazing list of good practices to make safer our GraphQL service can be found here

Let’s do it

First of all, we need to write the contract for our service. This will permit both client and server establish the services endpoints.

If you have experience with OOP you see what an easy to understand is.

The best way to understand GraphQL is implementing a GraphQL service.

The application

We will implement a GraphQL API that will helps us to organize meetings in a company. The requirements for this application are:

  • The API must provide a way to add rooms, employees and meetings
  • Meetings can only be organized by employees but invited people can be both employees and external workers.

Write the domain models in the contract (the GraphQL schema)

Writing GraphQL contract

Adding descriptions and comments to our API

Below, we see how API’s are described in GraphQL. This is really important when a client needs to understand our API’s.

A documented GraphQL schema

Write operations provided by our API (query and mutations. Subscriptor will be explained in a future post)

Operations in GraphQL schema

Code implementation

Since this workshop is not focused on how implement a GraphQL you don’t need to spend time on it. On the hand, please checkout this project that implements the operations in the above GraphQL schema

To run the project, take one of the options

  • make run: Docker is required
  • make local: In this case you need to get a mongodb running locally on port 27017.

Once our GraphQL application is up and running we can consume the services.

Now you can save data into the database by making use of mutations

or read data with queries

As it was mentioned on the above, this is a material used by myself for doing a “Workshop of GraphQL”. Even the article go through several points, they are not taken in dept. Deeper articles are coming soon!