Why You Should Care About GraphQL

Ben Lloyd Pearson

Mar 02, 2020

Learn the use cases that benefit the most from using GraphQL and how to best implement it.

What is GraphQL?

In 2012, Facebook faced a problem: they wanted to improve the functionality of their news feed, but they were pushing the limits of their mobile app’s ability to download frequent, small updates. REST was not a viable solution because the structure of their internal data models didn’t follow REST conventions. They also required high bandwidth efficiency since they were dealing with mobile devices that don’t always have a reliable internet connection. Enter GraphQL, which they eventually released as open source in 2015.

GraphQL solves two major problems. First, it enables API consumers to structure their requests in a way that mirrors the response, both in hierarchy and in the data that is returned. This makes it easier to return only the data you need, unlike REST which returns all data that is available, thus taking up precious bandwidth. Second, REST requires API providers to build functions for each specific query and filter they want to support. GraphQL, on the other hand, supports queries and filters for all data fields by default. We’ll take a deeper look at these things in the next section.

GraphQL is often called the REST killer, so should you get ready to upgrade? Download our guide on GraphQL vs. REST to find out what you should consider before making the move.

Why Use GraphQL?

Based on the use case of Facebook, you might have already guessed that GraphQL is best for use cases where something needs to make frequent updates that include only a specified set of data. This makes it great for mobile applications since bandwidth is both precious and unreliable. Any data that’s unused from a REST response is wasted bandwidth, and GraphQL helps you avoid this.

Reduce Bandwidth Requirements

Let’s take a look at an example that demonstrates this difference. Say we want to build an app that keeps track of our best friend’s birthday, and we want to access data that represents the date of their birthday and their favorite food, which we’ll use to buy them a gift.

The typical REST request would look like this:

$ curl -X GET 'https://my.api.com/person/my_friend'

The REST response would look something like this:

{
  "name": "My Friend",
  "birthday": "1971-01-01",
  "favorite_food": "Pizza!",
  "id": "my_friend",
  "hair_color": "Black",
  "eye_color": "Blue",
  "car": "1981 DeLorean"
}

This response includes all the information we need, but it also includes things we don’t care about for this use case, like the color of our friend’s hair and the car they drive. GraphQL is better in this situation because it allows you to request only the data objects you care about. So, the request would look like this:

$ curl -X GET 'https://my.api.com' --data '
{
    person(id: "my_friend") {
        birthday
        favorite_food
    }
}'

And this would be the response:

{
  "data": {
    "person": {
      "birthday": "1971-01-01",
      "favorite_food": "Pizza!"
        }
    }
}

Notice how the results that are returned perfectly match the hierarchy we used for the request. This results in significant bandwidth savings, particularly for objects that have tens or even hundreds of data points.Even more so when you multiply that across millions or billions of API requests.

You might also notice a difference in the URL that is used for the GraphQL request. This is because GraphQL uses a single endpoint and returns data representations that match the payload its given. This contrasts with REST, which uses URL endpoints like `/person/my_friend` in the example above.

Manage Complex Data Structures

GraphQL is also good for situations where you need to implement user interfaces that include complex data structures. For example, what if, as part of our example above, you also wanted to return a list of stores where you can buy a gift card for your friend’s favorite food? In this case, the favorite_food object will have it’s own data schema that can be returned,including a list of stores.

With REST, you’d probably need to make two requests, the first to get your friend’s favorite food, and the second to return information about this food. In the following example, take note of the difference between the two endpoints that are called with cURL.

$ curl -X GET 'https://my.api.com/person/my_friend'


{
  "name": "My Friend",
  "birthday": "1971-01-01",
  "favorite_food": "pizza"
}


$ curl -X GET "https://my.api.com/food/pizza"


{
  "name": "pizza",
  "stores": ["Pizza Express", "Gormet Pizza Delivery", "AAA Pizza"]
}

With GraphQL, you can do the same thing with a single request that returns data for both your friend and their favorite food, thus reducing the number of API requests we need to make.

$ curl -X GET 'https://my.api.com' --data '
{
    person(id: "my_friend") {
        birthday
        favorite_food{
          name
          stores
        }
    }
}'
 
{
  "data": {
    "person": {
      "birthday": "1971-01-01",
      "favorite_food": [
        "name": "pizza",
        "stores": ["Pizza Express", "Gormet Pizza Delivery", "AAA Pizza"]
      ]
        }
    }
}

We could take this further to request additional information for the store objects such as the website URL and physical address if we also wanted to use that data. Keep in mind that each of these objects probably have data fields we don’t need for our use case. With REST, each of these objects will return all data, which can quickly add up in situations that have unreliable internet connections or bandwidth.

GraphQL introduces it’s own potential downsides to query efficiency. Learn about how to plan for these in our guide on GraphQL vs. REST.

Who Uses GraphQL?

Quite a few companies are making the jump to GraphQL, this is evidenced by all of the companies that have joined the GraphQL Foundation. GitHub is one notable company who released v4 of their API with GraphQL; they give the following reasoning:

“GitHub chose GraphQL for our API v4 because it offers significantly more flexibility for our integrators. The ability to define precisely the data you want—and only the data you want—is a powerful advantage over the REST API v3 endpoints. GraphQL lets you replace multiple REST requests with a single call to fetch the data you specify.”

Shopify released a GraphQL API in 2018 to make it easier to build and manage online storefronts, they like it because it helps reduce requests that are made to their API servers:

“GraphQL gave us big wins by reducing the number of round trips made to the server and giving us a well defined and strongly typed schema to work against. GraphQL has also played a major role in helping us find and fix bugs before impacting our merchant’s daily operations.”

Yelp released their first GraphQL API in 2017 and like it for how easy it is to access relational data:

“GraphQL also makes traversing graphs (and therefore relational data) very easy. Unlike most REST APIs, you don’t need to make multiple requests to pull relational data. Based on the schema, you can retrieve data based on the relations they have. For our API users, this means easy access to all the great business information we have available.”

Ready to Make the Move?

Is it time for you to make the move to GraphQL for an API you consume or produce? You’ll need to consider a few important components about caching, optimizing queries, planning and designing your API, and how you design and build your data models.

Fortunately, our guide, “GraphQL vs. REST: Is GraphQL the Future? How Can You Implement it Now?” can help you make that decision today.