Jakub Bem
September 17, 2020
9min read
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.
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.
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.
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.
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.
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:
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:
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.
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 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.
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.
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.
Let's talk about your project!
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:
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.
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.
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.
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.
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.
Similar read
January 14, 2021
7min read
JAMstack is a modern web architecture, which significantly improves and (for the lack of a better word) revolutionizes how businesses build web applications and websites.
January 06, 2021
4min read
In 2021 Google will follow through with a few significant changes in their search algorithms that will impact technical SEO of virtually all websites and e-commerce platforms.
October 08, 2020
6min read
In our blog post about Wordpress, we explained how you can take advantage of modern web technologies to create lightning-fast frontend for websites. Additionally, in our introduction to GraphQL, we explained APIs and what makes GraphQL so great. Today we will merge both these topics and show you how to support your lightning-fast interfaces with a brilliant backend solution. Headless CMS, here we go.
Tell us more about the project you want to work on