How to get exactly what you ordered with GraphQL

Today we are going to talk about APIs (Application Programming Interfaces), and more specifically, about REST and GraphQL. Why does it matter to you?

Understanding how modern infrastructure works can be very beneficial when making a tech decision for your project. So the next time you decide to work with a software team, you will know what to ask about 😎

We will keep things as simple and clear as possible, so if you are an advanced programmer, you might want to skip some parts.

What’s an API?

To better understand what an API is, it’s necessary to understand how your website or mobile application (a.k.a. frontend) communicates with the server (a.k.a. backend).

Let’s say you want to Google something. You type in the search - “cute dogs in pajamas”, click enter and get hundreds of pictures and links to websites with cute dogs in pajamas.

Now what’s happening behind the scenes is the website (Google, frontend) sends your query (“cute dogs in pajamas”) to the server (backend). The server prepares an adequate response and sends it back to you.

A messenger or… a waiter

An API is a messenger that first delivers your search query to the server and then brings the response back to the website which displays it for you.

You can think about it like this: you sit at the table in a restaurant (frontend) and the waiter (API) takes your order to the kitchen (backend) and then brings the food (data) back to you.

Before GraphQL there was REST API

REST has been widely used for a long time now and it’s become the standard way for getting data from the server. However, when its concept came to life, websites and applications were much, much less complex and the development pace was slower than it is today.

What is REST?

REST is a specific approach to writing an API architecture. Its basic idea is that requests are sent over HTTP and you have an endpoint for each of them.

Let’s say you are on an Instagram-like app and want to display someone’s profile. To keep things simple, the profile consists of their name, last three followers and the pictures they uploaded.

Now, when we are using REST as our messenger to deliver the data, it will most likely take multiple trips to complete the request.

Endpoints

If we want to see the name, last three followers and pictures of the user, we will need to ask three separate times.

On the first trip, we want to get the details of our user with an id (in our example, fgkz3913). This data can be requested from an endpoint looking like this:

fakeinstagram.com/users/id

So we go to fakeinstagram.com/users/fgkz3913 and we receive information about the user profile: Name, Surname, Profile Picture, Date of birth and so on.

Wait. But we only wanted to show a name, right? Yes, but the REST architecture works in such a way that all this information comes as a package.

Okay, so from fakeinstagram.com/users/fgkz3913, we got plenty of data and extracted our name - Ann.

Now for the second trip, we are going to ask about the last three followers. This time we are getting that information from fakeinstagram.com/users/fgkz3913/followers.

Unfortunately, again, at this endpoint, we receive a list of all the followers, with their profile pictures, age and date of birth. It looks like this:

• John, age 19, picture, date of birth
• Jamie age 24, picture, date of birth
• Jenny age 20, picture, date of birth
• Joanne age 27, picture, date of birth

And so on.

Ugh! All right, we just needed three last followers by name, so we extract that - John, Jamie and Jenny.

For the third request, we are going to

fakeinstagram.com/users/fgkz3913/pictures

and luckily get a list of all the picture URLs like this:

• fakeinstagram.com/fgkz3913/picture1.png
• fakeinstagram.com/fgkz3913/picture2.png

• fakeinstagram.com/fgkz3913/picture3.png

Done, we can finally display the profile. Took a while, right? It might feel like asking one waiter to bring us water, another one to bring us juice and finally the third one to get the main meal. Then, when they deliver your orders, you end up with five different juices, three types of water and seven main meals to choose from.

Instead of simply ordering everything at once from a single waiter and getting exactly what you wanted in the first place.

REST patterns

Let’s be fair - REST isn’t all bad and it still powers a vast percentage of the web and mobile apps. Modern architectures provide great techniques to make data fetching more manageable.

For example, one of the ways we could address the “multiple waiters” issue above would be to build a single endpoint for our user profile.

Now at fakeinstagram.com/userprofile?id=fgkz3913 we can find all the necessary data with just one trip - this endpoint will provide us a name, last three followers and a list of photos all at once.

But… to do that, we need to ask our backend engineers to write this specific endpoint. And it’s going to reflect exactly what we are currently displaying in the user profile.

What if we decide that instead of just a name, we want to display a surname and profile picture too? Yep. We are calling our backend engineer again, to make changes in the API.

That’s a quick death for rapid prototyping and ad-hoc product adjustments. That’s especially important today, in the world of startups, MVPs, POCs and ever-changing online products.

And that’s one of the reasons why…

Facebook invented GraphQL

Facebook was also facing the challenge of downloading lots of data on mobile devices.

As we know, even in 2020, a good mobile internet connection is not a guarantee. It’s essential to minimize the amount of data that the user needs to download.

Facebook invented GraphQL in 2012 and, at first, used it for their native mobile applications. Then in 2015, they decided to opensource the project.

It can be used with any programming language and framework, and lately, it’s gaining widespread popularity. At Blazity, we are using it for almost every project and we absolutely love it.

Many large companies do as well - amongst companies using GraphQL we can find giants like Airbnb, Facebook, Audi, Github, Twitter, New York times and many more.

Okay, so what is GraphQL?

GraphQL is a query language (hence the QL in the name) for APIs. It provides a new way to request and send data between apps and servers. One of the great things about it is that it always provides a single endpoint for all of our requests, thus allowing developers to get precisely the data they need.

Let’s go over our fake-Instagram example again this time using GraphQL.

Single Endpoint

Since we have a single endpoint, we no longer need to make three separate requests. This time we are asking only once and receiving everything we need in a single package.

Since we are using a Query Language, we implement it similarly to database queries - we decide which attributes we need.

Here’s how our query could look when asking for the name, last three followers and pictures on our fake-Instagram platform.

As you can see, it’s very straightforward. We first decide which user we are asking for (by providing an id in line 2) and then we define which data exactly we need for that user.

We know that we need the name (line 3), the last three followers (line 4) and pictures (line 7).

Quite simple, and so is the response that we get from the server. It could look like this:

Now we have exactly what we need, nothing more, nothing less.

In line 4, we have the name of the user we are looking for; then we get names (and just names, no unnecessary data) for our last three followers (lines 6-8) and URLs to the pictures posted by our user (lines 11-13).

This way, we don’t waste any precious bandwidth downloading the data which we don’t need. And we only make a single request.

Overfetching and underfetching

Our fake-Instagram also acts as a great example of overfetching and underfetching (here fetching refers to getting data from the server).

Overfetching means that we are getting more data than we need. It can cause significant unnecessary data downloads, an especially important factor on mobile devices.

Like in our example, we were overfetching the data about the followers, getting the list of entries like:

• John, 19 years old, profile picture, date of birth

instead of getting just three names that we needed.

Underfetching happens when we have to make multiple requests to get all the necessary data. In our REST example, we were underfetching - instead of asking once for name, last three followers and pictures, we had to take three separate trips.

The single endpoint architecture of GraphQL elegantly fixes both of these problems.

What’s more - each query can be modified on the go, so if this time we decided to also display a surname and profile picture, we would adjust our query like this:

This makes prototyping super quick and easy.

Schema definition and other dev things

GraphQL is loved by the developers and for good reasons. One of the most important ones - it uses Schema Definition Language (SDL), which defines how a client can access the data. It clearly defines the operations (queries, mutations and subscriptions) supported by the API.

SDL acts as a contract for how all the API operations in our application are going to look. As a result, our frontend team knows exactly what kind of data they can get and how to do it.

Now our frontend team can quickly build an application with mock data and connect to the GraphQL API later when the server is ready. And they can do that without ever contacting backend engineers. This allows for much faster prototyping and product development.

Auto-generated documentation

All the API documentation in GraphQL can be automatically generated based on the schema. And if your schema evolves - no problem, documentation will be automatically updated.

Opensource

GraphQL is open-source, which means that thousands of individuals around the world are working together to make it better.

It also means that when you encounter problems or unusual challenges, there’s a big community to whom you can reach out for help.

Summary

REST still powers most of the online world today and we expect that it will stick around because it has great use cases.

However, right now, GraphQL is gaining widespread popularity. We expect that in the coming years, it’s going to become a standard for the new web and mobile applications.

If you are ready to start using it in your projects - don’t hesitate to contact us and we will show you how cool it is 😊

If you are a programmer and you are interested in exploring the GraphQL landscape, we highly recommend howtographl resources. They are a great starting point and you will be using the technology in no time.