Introduction to GraphQL

Image source: https://www.amazeelabs.com/en/journal/introduction-graphql

Desktop and mobile device are fundamentally different. One that immediately stands out is their size difference. There are various consequences from their size difference: computing power, portability, resource consumption, etc. This results in the difference in how the users use the applications, ranging from when they are used to what the users expect from them, and unavoidably, how developers build the application for the users.

One thing that developers have to consider when building an application that targets both desktop and mobile is the user interface. Screen space is a rare commodity in mobile devices. The way information presented on desktop and mobile device most of the time is different. Some websites even have m (mobile) sub-domain to serve users using mobile devices.

When an application wants to populate its user interface with data, they usually make a request to its back-end server. In REST architecture, information is grouped by resource, and every resource has its own address or locator. Data served from each locator are determined by the server. The client only sends a request to a locator then the server will give the resource the client asked.

With its simplicity, REST has served our needs for quite some time and basically becomes the de facto standard of web services API. But with technological advances and changing requirements, REST has shown its age. The shift of trends towards mobile-first society drives Facebook to develop its own solution to solve the development problem due to the differences between desktop and mobile.

What is GraphQL?

You might have heard about GraphQL before. Dubbed as a RESTful killer. Someone who dares to stand where REST stood. Used by big names, such as Facebook, Twitter, and GitHub. So what is GraphQL really?

GraphQL is a query language developed internally by Facebook, but then was open-sourced in 2015. Unlike REST, GraphQL is actually just a query language, not an architectural style. It is also not a protocol, unlike SOAP. But it still defines the API of a program. We’ll see the syntax of GraphQL and how it solves problems that exist in REST API.

Why GraphQL?

We’ll start with a simple query. Let’s say we have a database that stores article details: articleId, title, author, and publishedDate. Here’s a possible query to get the title and published date of all articles:

{
  getAllArticles {
    title
    publishedDate
  }
}

In REST, we most likely are going to send a request to a URL, let’s say api.hmif.tech/articles. But we probably are going to get all four fields of all articles. From this example, we can already see GraphQL solves a problem called over-fetching. To explain it simply, over-fetching is when we get more information than we need. GraphQL lets the client specify what data it needs.

Let’s move on to a more complex query. Let’s say we want to get the title of an article with articleId=1 and the title of all articles its author wrote. For example, to create a list of “Other articles you might like”. Here’s a possible query to do that:

{
  getArticle(articleId: 1) {
    title
    author {
      articles {
        title
      }
    }
  }
}

In REST, we probably are going to send a request to api.hmif.tech/articles/1, then send a request to api.hmif.tech/authors/:authorId, then send a request to api.hmif.tech/articles/:articleId for each article the author wrote.

From this example, we see GraphQL solves N+1 problem. N+1 problem is when you fetch a collection (1 request) and have to fetch the details for each element (N request). You probably can include the details when you fetch the collections, but then it might result in an over-fetching problem.

There’s also nested query problem. REST makes it hard to query information within the information. This is the reason Facebook developed GraphQL in the first place.

“REST really wants to have one model per URL. Recursion is just really difficult to correctly model in that framing, especially when, in order to resolve any of the links between these things, you need to go back to the network. And here we’re talking about relatively early days of the smartphone world where the vast majority of people are still on 3G, 4G isn’t even a thing yet, let alone LTE. So network is absolutely the bottleneck”
- Lee Byron, one of the co-creators of GraphQL

Maintaining REST API for multiple clients also pose to be quite a challenge. Say we have a mobile client and a desktop client that fetch data from REST API. The mobile client wants to show only the article due to screen size constraint, but the desktop client also wants to show its related articles and most popular articles. Should the article API include related articles in its data? Does the desktop client need to send two requests to get the articles and most popular articles? Or should we provide two different APIs, one for desktop and one for mobile?

You can see that as the type of client grows, the API becomes more and more complicated. REST architecture is not made for one-size-fits-all API (or one-endpoint-fits-all API). In modern applications, we have many different types of client: desktop, mobile phone, tab, even IoT devices — each with different needs. GraphQL offers a solution to decouple apps from services by introducing a flexible query language.

In addition to that, GraphQL eliminates the dependence of the client team to the back-end team. Client team usually iterates and experiments frequently. Whenever there’s a data requirement change — maybe due to UI/UX design changes — client team doesn’t have to ask the back-end team to add or modify something. They can simply change their query to accommodate the changes.

With that many advantages over REST, GraphQL comes with shortcomings that are not trivial to solve, which deserve an article of their own. Some of them are query complexity, rate limiting, and caching.

There are still many areas that are not covered in this article. But I hope this article gives enough information for readers who wants a quick introduction to GraphQL.

Source:
- https://blog.restcase.com/the-rise-of-rest-api/
- https://code.fb.com/core-data/graphql-a-data-query-language/
- https://www.robinwieruch.de/why-graphql-advantages-disadvantages-alternatives/
- https://webapplog.com/graphql/
- https://www.quora.com/Is-GraphQL-a-REST-killer
- https://graphql.org/users/
- https://www.programmableweb.com/news/what-graphql-and-how-did-it-evolve-rest-and-other-api-technologies/analysis/2019/07/31