Building a Web API using GraphQL vs. REST

API is short for Application Programming Interface. APIs define how applications interact with each other. We might want to build a Web API to enable external applications like desktop or mobile clients to interact with our services.

When building a Web API for external clients, there are two popular options to choose from. These are REST and GraphQL APIs. In this post, I will try to clarify the differences between these two ways of building APIs to help us make the best decision for our projects.

REST (Representational State Transfer)

REST is short for Representational State Transfer. It is a set of architectural principles that describes how systems over a network (like the internet) should communicate.

An API that follows the REST principles is said to be a RESTful API or REST API in short. It is one of the predominant ways of building Web APIs. These REST principles guide us to build APIs that have a clean separation between the client and the server and that are easily discoverable so that the clients can navigate the API without relying on external documentation.

When building REST APIs, we define endpoints that point to the resources that are exposed by the server. We can think of resources as the entities that make up a business's data.

Imagine an online store that displays and sells a bunch of products. The REST API that powers the front-end of this store might have an endpoint like www.example.com/api/products.json, which exposes the Products resource (the products that this online store has) to the clients.

The client can interact with this resource using HTTP methods such as POST, GET, PUT, PATCH, and DELETE to perform operations like creating a resource, reading a resource, updating the resource, and deleting that resource.

Say a client wants to interact with the products resource to see what products this online store has. They can perform a GET request to see what products are available in this store, make a POST request if they want to create a product, use the PUT (or PATCH) method to update a product, and DELETE to delete a product.

Defining the API as a collection of resources and allowing interaction with these resources using the underlying communication protocol (HTTP for a Web API) is something that is prescribed by the REST principles.

Here are some of the advantages and disadvantages of REST APIs.

Advantages

• REST principles help us build APIs with well-defined interfaces that are easy to discover and navigate. It also helps us achieve a clean separation between the server and the client.
• REST leverages the HTTP protocol; this makes data caching relatively easy.

Disadvantages

• REST is not a specification. It is a set of principles. As a result, it doesn’t provide strong guidance in how anyone should implement those principles. That can result in many divergent implementations that claim to be RESTful when they are really not.
• When we query a resource on a REST API, we receive all the data related to that resource (unless some filtering logic is built into the endpoint). This might be acceptable if the API was built for a single client, but it can become problematic when serving multiple clients. There could be desktop computers, mobile phones, and smartwatches as a client to the same APIs. The data requirements for these clients could be wildly different. Serving them the same amount of data is not practical or efficient.
• On a related note, since we serve all the fields to the client in every query, there isn’t an easy way of telling which fields are actually needed by the clients. This makes removing (deprecating) fields very difficult when building REST APIs.
• Web applications can require a lot of different kinds of data to be displayed whenever a page is visited. For example, an online store product page can have information about the product, the shipping times, the inventory amount for that product, products related to this product, and completely different products that might be on sale. It is very common that we might have to call multiple endpoints to gather all the needed data for a given page. This can result in making a lot of separate calls to the API. This can result in efficiency and performance issues.

GraphQL

GraphQL is a more recent paradigm for building APIs, developed and open-sourced by Facebook (now Meta). GraphQL consists of a query language that describes how the clients should communicate with the server and a server runtime that handles those queries. It has been developed to address some of the shortcomings of REST APIs.

In a REST API, the client interacts with the server through resources exposed through multiple endpoints. Using GraphQL, the clients interact with the server using queries through a single endpoint. GraphQL queries are written in a human-readable language called gql (Graph Query Language). One of the strongest aspects of GraphQL is that the clients can craft their own queries to receive the exact data they need for their purposes. For example, a client for an online store can make a query like this:

{
  products {
    title
    inventory
    price
    relatedProducts {
      title
    }
  }
}

This query is fairly straightforward to interpret. It is essentially asking for the title, inventory amount, and price of all the products and the titles of all the products related to this product in a single HTTP call! The client will be getting the exact data that it is querying. Nothing less, nothing more. This makes GraphQL APIs extremely data efficient.

The shape of a result for a query would match the query. Here is an example of what it might look like:

{
  "data": {
    "products": [
      {
        "title": "The Best T-Shirt",
        "inventory": 32,
        "price": "80USD",
        "relatedProducts": [
          {
            "title": "The Second Best T-Shirt"
          },
          {
            "title": "Stylish Sunglasses"
          }
        ]
      },
      {
        "tile": "The Best Pencil Case",
        "inventory": 5,
        "price": "20USD",
        "relatedProducts": [
          {
            "title": "Red School Bag"
          }
        ]
      }
    ]
  }
}

You might wonder how the client knows what is available to request in the API. This is made possible by a type definition file called schema that defines all the fields and data types made available by the API. A client can query this schema file to see what is available for them to know exactly what data they can receive.

I have written more about building GraphQL servers in another post if you want to learn more about this approach.

Here are some of the advantages and disadvantages of GraphQL

Advantages

• GraphQL gives the clients a lot of power and control by enabling them to query for the exact data they need.
• This fine-grained access model also makes it easier to understand what fields are being used by the clients. It makes removing (deprecating) API features much easier.
• GraphQL schema makes it easy for clients to understand what data is available and provides type safety.

Disadvantages

• Certain things like caching and rate-limiting could be hard to implement when working with GraphQL.
• A client might also become more complex and require a framework (such as Apollo Client) to work efficiently with a GraphQL API.

Summary

When building an API, choosing the right option for your project boils down to the requirements you have. GraphQL seems like a great choice if you are serving many different kinds of clients, and performance could become a concern, but it definitely comes with a certain level of complexity. There is no wrong or right decision here. It is essentially about what you and your clients need from the API.

It is important to note that the decision is not mutually exclusive. You could still have a REST API for certain actions like authentication and perform other interactions through GraphQL.