What is GraphQL and how does it differ from REST APIs?

The technology world is filled with hype spiced up with jargon. Each passing day there is a new technology that supercedes the previous one. For the last few years RESTful APIs have been the hottest thing.

But today many vow to the name of GraphQL and dance on the graves of REST APIs. But what exactly is GraphQL and how is it different from REST APIs?

Traditionally web applications have worked so that the server sends a complete page to the client (the browser). This model has been changing towards one where the server sends the browser a complete JavaScript powered application on the first round trip and subsequent communications only contain data. So no more sending back and forth layouts for a complete page.

REST APIs and GraphQL are both technologies that allow this new breed of applications and servers to communicate with each other. For end users both accomplish the exact same thing and an application using GraphQL is inherently no better than one that implements REST. In addition it's worth noting that both technologies will continue to exist as they're not complete equivalents.

As a term REST (for REpresentational State Transfer) is the broader one out of the two. It covers a wide range of implementations and it's not a standard but simply a loose term that defines the way things are done. This is why a client application using a REST API is often very coupled to the application running on the server side.

While REST is somewhat ambiguous, GraphQL is a much more clear term. As an open protocol protocol that originates from Facebook it's much more clearly defined entity. While the name implies that GraphQL would have something to do with Graph Databases, this is not the case. GraphQL is a higher level communication protocol, rather than a query language for Graph Databases. GraphQL is robust and used by millions of people in billions of requests each day on Facebook mobile applications.

In addition to these two, there older and somewhat more cumbersome SOAP protocol continues to be widely in use. It is however not common to new endeavours using SOAP as their communication protocol of choice. In addition a technology called Falcor from Netflix is an option, but by large the choice for developers is between a RESTful API and GraphQL.

So which one is better, GraphQL or REST?

As said, neither one is superior to the other. While a REST API built on certain ideals can be suboptimal for certain applications. A good example are mobile applications, where a generic REST API implementation tends to result in a large number of small queries. GraphQL by nature steers development towards larger individual requests.

Each individual network request aways has a cost in overhead. This is highlighted in mobile applications where a single large request results in better performance than ten smaller ones. While this is alleviated by the lower level improvements in HTTP/2, it can still lead to a significantly worse user exparience.

Another notable advantage that GraphQL holds is that it's clearly specified. This is why any application that supports GraphQL could talk to any other application supporting GraphQL. With REST APis there is no such guarantee. For example WordPress and Drupal REST APIs are completely different and switching between them is not a trivial operation.

The philosophy behind RESTful APIs is the same, but they are not guaranteed to be mutually compatible. This is why a seemingly open REST API is often used to build a tight dependency / coupling to the specific flavour of REST that the application speaks. This makes decoupling using a headless CMS with REST somewhat of an illusion.

There are efforts like Hydra to further specify REST as a more generic option, but for true decoupling from systems GraphQL as an independent and specified standard is arguably the better option in 2016.