GraphQL or REST

For a long time now, REST has been the most popular protocol for sending information over the web. But in the last few years we have seen a great increase in the popularization of GraphQL. Which supposedly came to solve some of the problems of REST.

But first of all let's have an idea of what an Api is.

What is an Api?

You may not know what it means or what it does. But Apis are working behind the scenes to provide you with richer digital experiences.

It is a standardization for applications to communicate with each other to provide information and functionality without human intervention.

I believe you are still confused, because I was not very clear with my explanation. So I will use this image to give an example:

This is the most popular example and it was with which I learned the concept of how an Api works.

The way an Api works is usually compared to ordering food at a restaurant, where you represent the customer (the web, mobile or desktop client), the waiter represents the Api and the chef represents the server. You examine the menu, choose the meal you want and order from the waiter. The waiter takes your order to the chef. The chef executes it. Then, the waiter brings the meal to you.

What is REST?

It is an Api design paradigm designed to standardize web services through a set of constraints.

Using REST when building a web service makes it easier for clients and servers to get along, even when one is unaware of the other, so they can grow in a dependent way, as long as they follow the appropriate conventions.

What is GraphQL?

It was designed to handle a large volume of complex and nested data that is present in many modern applications.

Basically it allows clients to have the possibility to obtain only the data they want from the Api. This gives tremendous flexibility from the point of view of the frontend.

What’s the Difference?

REST and GraphQL are fundamentally similar, as both include the idea of resources.

The core idea of REST is the resource and each resource is identified by a URL, and you retrieve that resource according to the HTTP verb. So it looks like this:

// GET /api/posts/10

{
  "id": 10,
  "title": "GraphQL or REST",
  "comments": [
    {
       "id": 1,
       "message": "bla bla bla"
    }
  ]
}

Notice that we have two resources, the first one is the post and the second are the comments. And whenever we make an HTTP request to this endpoint, all this data will always be returned, even if we only want the post data and not the comments.

GraphQL has a different approach, as mentioned earlier. This is because the two resources in the previous example are completely separate. First, we would have to define the data that both resources hold. And only after that we could query the data.

If we just wanted to get the data from the post, we would have to do it as follows:

//  query {
//    singlePost(id: 10) {
//      id
//      title
//    }
//  }

{
  "id": 10,
  "title": "GraphQL or REST"
}

However if we wanted to get only the title of the post and the comments, we would do it this way:

//  query {
//    singlePost(id: 10) {
//      title
//      comments {
//        id
//        message
//      }
//    }
//  }

{
  "title": "GraphQL or REST",
  "comments": [
    {
       "id": 1,
       "message": "bla bla bla"
    }
  ]
}

REST Apis issues

Some of the problems that are solved by GraphQL are the over/under fetching, the flexibility and the excessive amount of requests to Api.

These problems happen because the only way to obtain data in REST Apis is to make HTTP requests to certain endpoints in order to obtain certain structured data sets. And because of this, it is difficult to provide clients with the data they really need.

GraphQL Apis issues

In GraphQL, there is a common problem called the n+1 problem. This is because in GraphQL we execute different functions (resolvers), while in REST we have only one function (controller) per endpoint. That is, our Api will end up making several requests to fetch data for a given resource.

When should I use REST/GraphQL?

I have to mention that when we start a project, we should use tools that we are more confident to use. Each paradigm has its advantages and disadvantages, just as each has its own learning curve and challenges.

If you want to have greater compatibility with other types of clients (web, mobile and desktop) and tools or if you have a project that is easily structured, the use of REST would be ideal.

However, if you want to have the flexibility to choose which resources to consume with a single request to the Api or if you want to query only the data you want, using GraphQL would be ideal.

GraphQL Challenges

Although I am talking about Apis development, the differences between the two paradigms become great if we put the frontend in question.

From the point of view of the development of the frontend when consuming Apis with GraphQL it is a dream come true, because we have all the flexibility we want and it is not that difficult to implement.

However, the backend is totally different, because this is where the whole concept is different from what we are used to REST. And this is where all the complexity and the learning curve lies.

What about you?

Have you created GraphQL Apis in your projects?