GraphQL

3-minute read
development

What is GraphQL?

GraphQL is a query language created by Facebook in 2012. It’s creation was motivated by the increasing number of mobile users that introduced the need for optimization. On 2015, GraphQL was open sourced, and it’s growing fast since then.

When I think about REST APIs there´s a cool analogy that comes to mind: the food machine. When you want to get something, you press a combination of buttons, that simple. REST is just like that, you access a combination of endpoints and receive the desired responses. But what if you wanted a combination of parts of many objects? You would probably need to access multiple endpoints to get them. GraphQL solves this problem with an elegant solution.

Basic characteristics

  1. Describe your data (schema)
  2. Ask only for exactly what you want with possibility to ask for multiple data
  3. No need for versioning APIs

Schema

On GraphQL you describe a schema of your API and model your domain as a graph, as the name suggests. That is great for documentation and helps the communication with the clients. Also, it is easy to understand because the modeling resembles our natural mental models.

Introspection

To know more about the schema, the client has to ask for an introspection query that returns the JSON with the schema. That is where the security comes in, you should not let this be accessible to the public, if your API is not open.

Special types

  1. Query - getting data
  2. Mutation - mutate data
  3. Subscription - real time

Continuous evolution

You will never need a V2 of your API, because it is possible to deprecate old fields, that can still be consumed by older clients, but will not be available for new clients. That is specially useful if you want to keep backwards compatibility or your clients may take a wile to update.

Keep learning

To learn more about the schema, you can check out the GraphQL website.

Performance

So it is intuitive, good to use, but does it make any difference on performance?

Some comparisons I made using Github’s GraphQL and REST APIs showed that if you are only interested in the username, the REST API will send you 1.3GB in 650ms, while GraphQL will send you 54MB in 181ms. That is shockingly better, 23 times less network traffic and 72% faster.

Dev environment

The development environment is great! GraphQL has a playground that allows you to test queries, save them, and check their syntax. That makes it a lot easier to develop and debug, even in production.

Problems

1) Getting the whole application in one query

With resolvers and subfields related, sometimes it is possible to query the whole application once. That generates a lot of processing.

To address that, GraphQL processes each resolver separately, and enables you to use LRU caching for them. Also, there is a configuration you can set up to disable the desired level of sub queries to avoid infinite loops.

2) Error handling

Every developer is used to the way HTTP errors are handled, if something was wrong, you will probably get a non-200 response code.

In GraphQL every response is a 200 response, and the error will be returned to the response body. Although, it is not the most intuitive way, error handling on code is great, because it will always be type-safe.

Note that sometimes when a sub resolver fails, the error path can have some unpredictable behaviours.

GQLGEN

So, after all of that you decided you want to create your own GraphQL API in Go. The tool I recommend is GQLGEN.

It is:

  • Extremely simple to use
  • Generates code for you, which makes is type-safe
  • Very efficient

Now you can create your own GraphQL API in Go, and it will be type-safe and easy to use.

Read more