Main advantages of GraphQL as an alternative to REST

GraphQL is based on a simple idea, moving the assembly of a request from the server to the client. The client sees the overall strongly-typed schema instead of multiple REST endpoints and he builds the query he wants.

My first REST based web application, SPAs for Single Page Applications as we are calling it lately, dates back to 2005. It was a time when REST requests and Rich Internet Applications (RIA) used to be called AJAX and were mostly used to transport XML. My first REST request in JSON was a few months later. How refreshing it was compared to the XML hell used at the moment! No more unnecessary parsing, unreadable schemas or dirty SOAP.

REST served us well and will still do for a long time. However, there are situations where it is not optimal and where GraphQL is much more convenient.

GraphQL objectives

Data comes from multiple sources across the organization, owned and managed by multiple teams, stored in heterogeneous database backends and located on multiple platforms with complex access policies. Data Warehouses, Data Marts and Data Lakes expose datasets with their own requirements and set of protocols. Maintaining a coherent governance, defining efficient processes and ensuring final consumers leverage the data available in the organization is a challenge.

GraphQL aims at providing self-documenting APIs to end users, using data from any source, to build production-ready applications.

API catalog

GraphQL provides the missing manual when new incomers need to grab a knowledge of the company APIs. Because the data model is declared in a schema, it is easy to navigate through it and learn from it. It allows front-end developers to interact with different APIs without knowing the integration details for each of them. Various GraphQL tools provide a web UI to edit queries with auto-completion built-in and generated API documentation.

Speed of development

The rate to iterate and to prototype is much faster than with REST. It is no longer necessary to specify data requirements on the server side such as which fields from which models need to be fetched and exposed. With GraphQL, you define a schema, this is the model. The schema is the data model with all the properties its carrying. How to use the schema and consume its data is defined on the client side. It changes the way to interact with the data by freeing the integrator.

For example, if you need to change a property that is missing in REST, you have to change the server side code and reflect those changes on the client. While with GraphQL, you just declare a new property directly on the client where the data is used. Front-end developers don’t need to get in the server, assuming they have access to it. Junior and senior, they feels safe to use the data available. It makes them feel empowering. If a developer forgets to display an already available field from the model, he simply has to update his client.

Robustness of integration

Server-side developers also benefit from using GraphQL. On the server, a lot of data are being accessed, often in a very similar fashion. Records need to be merged or enriched to fit specific request requirements and sent back as JSON and the same integration process is repeated again and again for each new requirement. With GraphQL, since data is expressed by a schema, server-side developers don’t have to go through this process. Once you have your schema defined and the source of data being declared, you are no longer concerned with the logic and you don’t really have any future work to do.

An additional benefit is that it reduces the surface area of the applications both in term of potential bugs and security breaches. In case of any issue, the team can look at one place, where the schema is defined, and not hunt through every source base to look among multiple REST APIs that could be impacted.

Guarantees in Refactoring

GraphQL clients statically analyze the query. The benefit is the ability to set up linting rules to detect a change in the schema which will produce an error. It allows teams to refactor their GraphQL query and ensure it reflects the new schema. For example, in case you wish to change the name of the property to be more descriptive, you can rename the property, run the linter and know exactly which query is going to break up and fix it right where it is being used. It can be coupled with Flow (or TypeScript) to trace all the variable names being changed.

Additional benefits

GraphQL comes with multiple features such as subscriptions, access control, monitoring or error handling. The GraphQL server can provide multiple services including a caching layer, authorization rules, and access traceability. It is also possible to federate multiple servers to act as a single entry point data provider. Libraries like Appolo client make sure your code is robust by enforcing failure handling.

Not just for the WEB

GraphQL is transport agnostic and is not tied to HTTP and JSON. Like gRPC and Thrift, it can serialize data in a binary format and transport it over more efficient protocols. The query language coupled with a schema in the backend is the killer feature and it does not only apply to web applications. Many users and use cases in the Big Data and Data Science fields will benefit from integrating data exposed by GraphQL.

Considerations

People who will benefit the most about importing GraphQL into their organization are large teams, particularly the ones facing integration issues. Individuals probably won’t get any benefits of using GraphQL over dedicated REST queries.

At this point, most of the GraphQL APIs are published internally in companies but are not yet publicly exposed. GitHub has done it but it implies adding some mechanisms to ensure security and control any potential abuse. It lets people write semi-arbitrary queries against exposed data sets. For example, it is possible to define alerts when queries reach a certain threshold and are considered particularly slow.