GraphQL: An Introduction

GraphQL was created by Facebook in 2012

Like me, you have probably seen GraphQL mentioned so many times across various different projects, blogs & job descriptions and much like me, didn’t really have any idea what it actually was. So I thought it time to fully investigate what it was and why it is popular enough to be everywhere but not quite popular enough to be everywhere.

GraphQL is essentially a way to more efficiently retrieve data from an API. It does this via declarative data fetching, where you specify precisely the data you want to retrieve from the API and you will receive nothing more and nothing less than that data. This means that it only requires one end point, as opposed to needing to use multiple endpoints each with different returned data structures. There are numerous pros and cons to using over GraphQL over the more standard REST which we will go over soon but It’s important to note that in it’s essence, that is all GraphQL does and all it is designed to do.

A Little History

Representational state transfer (REST) has become the standard way to extract data from a server. It is relatively simple to understand and implement and so has become very popular among developers. However, it has drawbacks, especially with regards to data-use that could cause slow performance which meant that in 2012 Facebook started to use GraphQL in their mobile apps. This is around the same time that Facebook was developing and publicizing React.js and it was at the React.js Conference 2015 that Facebook publicly spoke about GraphQL and announced plans to make it open source.

Why is it necessary?

RESTful APIs have become the standard because of their simplicity and benefits such as stateless servers. But they suffer from an inflexible and inefficient structure. With a RESTful API you gather data by accessing multiple different endpoints.

For instance, these could be the /users/<id> endpoint to fetch the user data. You may also need to send another request to /users/<id>/pictures to see their uploaded pictures and also one to /users/<id>/comments to fetch their comments. This is potentially three separate requests being made.

In GraphQL, you only need to send one query to the server which will include the exact concrete data requirements that you are looking for. The server can then respond with a JSON object with your required data.

For example the query below:

Query {
User(id: “1”) {
name
pictures {
img_url
}
comments(last: 3) {
text
}
}
}

Will return the following JSON:

{
“data”: {
“User”: {
“name”: “Adam”,
“pictures”: [
{img_url: “www.pictures.com/1" }
],
“comments”: [
{text: “this is” },
{text: “an example”},
{text:: “comment”},
]
}
}
}

The clear and obvious benefit of this approach is that we are eliminating over and under-fetching. We are only getting back the data we explicitly request and need. As opposed to getting back too much data that is irrelevant to our needs, or having to make multiple requests to different endpoints because the first request did not supply enough data.

Overfetching can have huge problems with slowdown and data usage, this was especially the case with early mobile apps which were running on mobile data which were nowhere near the speeds today’s 5G is capable of.

The Schema

Another of the defining aspects of GraphQL is its strongly typed Schema. Unlike most APIs, which can often lack documentation or a clear ability to see how to use them, a GraphQL schema defines the different ways to use the APIs — through queries, mutations and subscriptions. This makes it clear to the use what is and isn’t possible and also helps speed up the process of understanding how to make those operations yourself.

Should I make the switch?

REST APIs are fantastic and are the standard for a reason but there are certain things they cannot do or cannot do as well as GraphQL. If you haven’t already come across these issues there isn’t an urgent need to change anything. However, because of its utility, GraphQL is absolutely worth using and playing around with a little. Something which we will be doing ourselves in the next edition of this blog series.

If you’d like to learn more about GraphQL, please check out the below links for comprehensive additional information.