3 months studying GraphQL

Iván Corrales Solera
4 min readMar 14, 2019


During the last 3 months I’ve spent a long time on understanding GraphQL but also researching on the best way to teach it to others.

1. There’re not silver bullets in Software development

Don’t think that GraphQL must be the technologies to be used in all your new projects. In fact,

I don’t trust people who wants to convince me that some new framework or programming language are silver bullets.

We could find several comparisons between GraphQL and REST trying to show us which one is the best… or even with GRPC.. Each software problem needs a different solution.

Sometimes a REST approach will be better than a GraphQL one. I will go through some points that I’ve learnt during this time.

2. Focused on client

Why should we implement a new API? Because someone is going to consume our services. So we should provide API clients what they really need and not only what we think we need to.

I like to compare Software issues with real life ones. Let’s think about a Pizza restaurant that decides to cook

  • All the pizzas will be served with corn.
  • We cannot choice the ingredients for our pizza.
  • We can only order a pizza. If we need two pizzas we will make the queue again.

This sounds crazy, doesn’t it? Well, that’s REST for me.

  • Usually most of REST API’s return a resource identifier or a creation date field or whatever other attribute that was decided by the API developer.
  • The server will always return the full resource. REST API clients cannot decide which information they want to retrieve. Therefore, server is wasting time and effort on providing some information that will be avoided by the clients.
  • We need to make a new request for every resource we want to consume or create .

On the other hand….

  • GraphQL provides the clients of our API a mechanism to decide which information needs to be returned.
  • A GraphQL client can take a piece of the full response and server won’t make any effort on providing the not desired information.
  • With a GraphQL API we can ask for as many resources as we need in only one request. Or we can create several resources of different type in a single request too.

3. Contract first

I love paradigms that take advantages of the contract. The contract is the base of building a good product. REST doesn’t provide a contract, and I will never do it.

Software documentation is not a contract, is just a something that needs to maintained in parallel with our Software!

GraphQL didn’t invent the figure of the contract in API’s development. When we built SOAP services we used to write a known WSDL that contained the definition of our services. On the other hand, WSDL was so heavy to write… Writing a GRPC API also implies to write a contract: the proto file, in which we define the model structure and the service signature of our API’s.

4. Typed syntax

I enjoy a lot coding with untyped programming language such as Javascript or Python. However, defining an API has bigger implications that decide the language to be used to implement it.

GraphQL provides with a short set of scalar types (just 5) but we can creates as new ones as we need. They will be described as part of the contract. So both client and server will know about the supported types.

5. Immature frameworks

GraphQL specification is so powerful but frameworks and libraries are not at all. After trying several frameworks in many languages I found that some points of the specification are hardly supported by frameworks right now; specially when we want to implement custom directives.

Facebook defines a specification whose main goal is providing a way to develop API that are focused on clients. However, they don’t provide frameworks that help us to implement API’s following the specification, so actually they are not thinking of its clients… the developers that need to implement the GraphQL services

6. Try and learn

Learning new things is a way to understand better the new things that are coming. We can not take the right decision when we don’t know all the options. And we will hardly understand upcoming technologies if we don’t understand the current ones.

Learning new technologies, Software paradigms or programming languages will help us to make a better used of the existing ones.

7. Read articles is fine when you are not a coder

If you only read articles or papers like this, you could get a good understanding about things but you won’t know how the things must be done. To learn things, we need to put them into practice.

During these months I’ve made a couple of events and prepare some workshops which are published on the Internet. If you really want to learn to building GraphQL API’s, I invite you to have a look at these workshops

These workshops will teach you to implement GraphQL API’s by going through the different parts of the GraphQL specification.