The bare minimum you need to know about GraphQL so you don't embarrass yourself in a conversation

I promise I'll save you some time on videos, articles and books by boiling down the basics you need to know about GraphQL into a single article.

Using REST to consume APIs (the well-known RESTful APIs) is probably the most widely used standard in the software industry today. With the HTTP protocol, its methods and the REST specification, we can read data from an API using the GET method, POST to create, PUT to update and DELETE to delete. All of this feels natural, but with the rise of SPAs (Single Page Applications) and the growth of mobile apps, some companies like Facebook started experimenting with and building new technologies to represent and consume data, and one of the technologies that came out of that was GraphQL.

With this article, I want to give you the minimum information you need to understand what this technology is about, its advantages and disadvantages, so you can have better conversations with your development team and figure out whether adopting it makes sense.

What is GraphQL?

In short, GraphQL is an open-source specification for a query language created by Facebook. One of the biggest problems with using a REST endpoint today is that the client has to consume all the data the server provides and, often, has to make several calls to different endpoints to gather all the data it needs.

With GraphQL, the client decides which data it wants to consume. This avoids what's called over-fetching, which is consuming more data than you actually need, and also the opposite, called under-fetching, where you need several calls to other endpoints to get all the data you need, which increases the network bandwidth used.

Figure 1: Example of a GraphQL Query and Response - Courtesy of: https://code.fb.com

History

In 2012, Facebook began an effort to rebuild its native mobile apps. Before that, its Android and iOS apps were views of the mobile version of the website. As these apps grew more and more complex, their performance started to degrade, resulting in frequent crashes.

While moving to native models and views, they realized for the first time that they needed an API with the News Feed data (which at that point was delivered only as HTML). Some of the options they evaluated were RESTful servers and FQL tables (Facebook's SQL-style API), but these were ruled out because they didn't reflect Facebook's model and how the data is consumed (which is nothing more than graphs of objects with JSON, for example). On top of that, it would have taken a lot of server-side code for the client to be able to do the conversion.

GraphQL was our opportunity to rethink mobile app data-fetching from the perspective of product designers and developers. It moved the focus of development to the client apps, where designers and developers spend their time and attention.Lee Byron

Main Advantages and Features

Declarative Data Fetching

GraphQL embraces a concept called declarative data fetching in its queries: the client making the request has the power to choose the response it wants to receive, such as the entities, fields and relationships, using a single query.

No Over-fetching with GraphQL

There's no over-fetching with GraphQL. With it, a mobile client can choose which fields it wants to receive based on the screen it's going to show.

Single Source of Truth

The GraphQL schema works as a single source of truth for the applications that use it. It provides one central place where all the available data is presented.

Strongly Typed Language

GraphQL is a strongly typed query language, and its queries are written using the GraphQL Schema Definition Language (SDL). Being strongly typed makes GraphQL queries less error-prone, since IDEs with autocomplete and validation support can check them.

Versioning

In GraphQL there are no API versions like you commonly see with REST. With it, you can "deprecate" the API at the field level, for example, and clients that query it will get a warning message saying the field has been "deprecated". This feature lets you evolve an API over time without having to create several resources like you do with REST (adrianolisboa.com/api/v1, adrianolisboa.com/api/v2, etc...).

Main Disadvantages

Rate Limiting

With REST APIs, it's easy to limit the number of queries to a resource per day. With GraphQL, since there's a single resource, it becomes hard to limit this by operation, because those operations can be simple or expensive.

Cache

Taking REST as an example again, with it you can think about caching at the level of the resources accessed through a URL. With GraphQL, caching becomes a more complex operation, because each query can be different from the next, even when it works on the same entity.

Apollo

I couldn't write an article about GraphQL without mentioning one of the main GraphQL implementations around today, Apollo. It provides a complete platform with both client-side and server-side implementations.

Figure 2: The Apollo GraphQL ecosystem - Courtesy of: https://www.apollographql.com/platform

Is GraphQL the new REST?

The creator of jQuery, John Resig, along with his friend Loren Sands-Ramshaw, are writing a [book about GraphQL](https://graphql

.guide/) where they claim GraphQL is the new REST.

Here's an episode of the Changelog podcast where John talks about why he's so excited about GraphQL and why he believes GraphQL is the new REST.

Who's already using it?

On this site, you'll find a list of companies that already use GraphQL. The list includes well-known companies like Atlassian, GitHub, PayPal and, of course, Facebook.

Here's a list of videos (in English) about adopting GraphQL:

I want to play around a bit, where can I do that?

If GraphQL isn't on your list of things to study in the coming days/weeks/months yet and you want to play around a bit, the GitHub GraphQL API Explorer lets you run queries against real GitHub production data.

I believe one of the best ways to learn a technology is by practicing it. For that, I recommend reading the book The Road to GraphQL by Robin Wieruch. In it, you'll learn about the subject in a clear way, with plenty of hands-on practice.