REST is not the first protocol for sending information on the Web. But it has dominated the API space for more than a decade.

Recently, the new GraphQL designed by Facebook has become more and more popular. It is intended to correct some of REST’s shortcomings, but no technology is perfect.

What are GraphQL’s advantages over REST? Why use one in your project?

Problems with REST apis

First, let’s discuss some of REST’s weaknesses and how GraphQL tries to address them. There are three main reasons:

  • Excessive number of visits to the server
  • Over-fetching/under-fetching
  • Inflexibility

Too many times the REST Api is used to access the server

Suppose we are creating a social media application. It might show all the users’ most recent posts, as well as their username and profile photos.

For example, in REST, you need to send a GET request to/API /posts to GET the post, which might return a JSON object containing the post title, content, tag, date, and possibly a user ID.

You might then need to send a GET request to/API /users/:id/ for each post to GET information about the user’s username, avatar, and any other relevant information.

That’s a lot of back and forth for a page when you consider that you might be making GET requests for each user!

With GraphQL, you can access the server at once and get everything you need:

query {
    posts {
        title,
        content,
        tags,
        date,
        user {
        	username,
            avatar,
            catchphrase,
            favorite_dog
        }
    }
}
Copy the code

On a small scale, accessing the server multiple times is not a big deal. However, once you have a lot of data to work with, minimizing API calls clearly benefits you. GraphQL makes this easy to do.

Over-fetching/under-fetching

Another existing problem is too much fetching and not enough fetching. In REST apis, when you arrive at an endpoint, you always get the same data, whether you need it or not.

Let’s say we just need someone’s username and avatar. If /user/:id returns their username, avatar, tagline, and favorite dog breed, you’ll get all that information, whether you want it or not.

On the other end, you might run out of crawls and need to go back to the server for more information.

To display individual user posts, we need user information and the content of the post. If I get the user from the user endpoint, I still need to click on the Posts endpoint and retrieve the posts using the userID.

// Get user information data first
GET /api/users/42

{
    "username": "Mr. T"."avatar": "http://example.com/users/42/pic.jpg"."catchphrase": "I pity the fool"."favorite_dog": "beagle"
}

// Next, get the user's posts
GET /api/users/42/posts

{
    "posts": [{
        "title": "Hello World"."content": "Hi everyone!"
        "tags": "first post"
        "date": "July 1, 2020"}}]Copy the code

As we saw in the previous example, GraphQL solves this problem by allowing users to use a single endpoint and get only what they need.

Inflexibility

Expanding on the previous point, REST relies on creating apis that meet the requirements of the front end. If you can predict what the front end will need when it hits a particular endpoint, you can precisely adjust the retrieved data to match that view.

This works well when the view is relatively static. But if your front end changes a lot, you need an API that can be more flexible in returning data.

Similarly, if your API is being used by a variety of different clients with different requirements, the flexibility of the REST API will not be suitable for your purposes.

GraphQL provides this flexibility by allowing data to be retrieved in different configurations.

query {
    users {
    	username,
        avatar
    }
}

// If you want to get the user's favorite pet dog

query {
    users {
        username,
        avatar,
        favorite_dog
    }
}
Copy the code

Should I use REST or GraphQL?

From this article, GraphQL may seem like it’s always better than REST, but it’s not. Every architectural decision you make when building an application has its pros and cons, and this is no exception.

Here are some things to consider:

If you need something easy to use, choose GraphQL.

There is a learning curve to using REST properly, and if you don’t already know it, you can use GraphQL to create a great API more easily.

If you use GraphQL, decide how to handle errors

REST apis take better advantage of HTTP’s error reporting features. If you don’t want to return 200 OK status for client errors (which is common in GraphQL), you need to think more about error handling.

REST may be a better fit for microservices

If you are using microservices on the back end, REST may be better suited for your purposes, as it is intended to separate concerns.

GraphQL’s unified data “graph” is great if you don’t need to use different, completely different resources that might be written in different programming languages, but not so useful if you have a more distributed back end.

The cache problem

Caching is built into REST, but you must use GraphQL to manage caching. If you don’t build the cache in place, all the efficiency gains you get from GraphQL’s more targeted fetching can be wiped out.

conclusion

As with all things, there are trade-offs to consider when deciding between REST and GraphQL. What you choose for the project will depend on your needs and resources.