Migrating to GraphQL: A practical assessment

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?

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?

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 News (side note: This 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.

REST exposes resources (side note: Which 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.

GraphQL’s approach provides a number of benefits:

• Objects and fields in a GraphQL database require type annotations. These annotations can be used to validate queries and provide descriptive error messages;

• Clients explicitly specify which fields they want. As a result, the server never sends more data than is necessary and response payloads can be kept as small as possible. Moreover, query logs can now be used to understand which and how fields are used by clients;

• Objects are modelled as a graph that can be traversed. This makes it a breeze to combine data from multiple sources using a single query;

• GraphQL comes with built-in support for field deprecation, which largely removes the need for API versioning.

So it’s basically client-side SQL.

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

• There’s no support for information hiding: clients will have access to the complete schema, but also need a thorough understanding of it if they want to construct useful queries;

• Any data you want can be requested via a single endpoint. This makes it harder to implement caching;

• Arbitrarily complex queries can lead to service degradation or even cause complete failure of the service.

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 counts (side note: I have no words for this.).