Migrating to GraphQL: A practical assessment (2019)

GraphQL logo with eye, surrounded by rays of light
You write the query, GraphQL does the rest

Facebook’s GraphQL query language helps you create APIs that are both powerful and flexible. Its proponents often like to claim that the days of REST as the prevailing API design paradigm are over, but the rest of the world hasn’t quite caught up yet. Is now the time to make the switch?

Why it matters

Contemporary Web applications typically consist of clients that communicate with the server via a REST-like API. This API lets clients create, access, modify, or destroy resources in a standardised manner.

Unfortunately, REST is not without its faults.

Many improvements and alternatives have been proposed over the years that aim to work around REST’s problems. GraphQL is one such alternative and has become quite popular in a relatively short time.

What sets GraphQL apart from those other approaches, and to what extent does it fulfil its promises?

How the study was conducted

The study consists of two parts.

The first part aims to increase the authors’ understanding of the claimed benefits and drawbacks of GraphQL. GraphQL is still an emerging technology, and as such is not well-described yet in traditional, peer-reviewed scientific literature. The authors therefore resort to a grey literature review, which covers a selection of 28 articles that have been featured on Hacker NewsThis is one of the best social news websites that you can follow as a developer, so make sure you bookmark it if you haven’t heard of it yet!.

The second part of the study digs deeper into some of GraphQL’s key characteristics: the authors migrate seven client applications from REST APIs to GraphQL and assess how the applications benefit from it.

What discoveries were made

REST exposes resourcesWhich are usually complete domain entities on a multitude of resource-specific endpoints. More in-depth information about related resources can be retrieved by issuing follow-up queries to the right endpoints.

GraphQL on the other hand provides only a single endpoint – but it’s a powerful one, that can be used to query a database.

Why you should adopt GraphQL

GraphQL’s approach provides a number of benefits:

So it’s basically client-side SQL.

Why you should avoid GraphQL

GraphQL won’t solve all your problems. In fact, it also introduces new headaches:

Is it worth it?

Migrating the seven client applications from REST to GraphQL tells us a lot about how and where it makes a difference.

GraphQL removes the need for follow-up queries in theory, but in practice there aren’t that many opportunities to reduce the number of queries: most client functions are relatively simple and as such never need more than one single request to a REST endpoint. Migration therefore basically boils down to replacing a single REST endpoint call with a single GraphQL query.

Fortunately, not all is bad. Responses from GraphQL queries are much smaller than responses from REST endpoints. For instance, the median number of fields in endpoint responses drops from 93.5 to 5.5. This effect can also be seen in response sizes: GraphQL responses can be up to 99% smaller than their REST counterparts – especially if clients are only interested in some aggregate result, like countsI have no words for this..

The important bits

  1. GraphQL is a strongly-typed query language that allows clients to query objects and fields from an object graph
  2. Using GraphQL probably doesn’t result in less API calls
  3. Responses from a GraphQL API can often be drastically smaller than similar responses from a REST endpoint