GraphQL vs REST

GraphQL is an alternative approach to provide an API, so it's natural to compare it with REST. In this chapter we'll look into the same data model and how we can represent that in the two ways. Then we'll discuss the benefits of using GraphQL.

What is REST

REST is based on HTTP paths and verbs to provide operations for resources. For example, let's consider a simple data model where we have users and users can have todo items. A simple API could offer retrieving, creating, and listing objects:

• GET /user => List users
• GET /user/:id => Get user by ID
• POST /user => Create user
• GET /user/:id/todo => List todos for user
• POST /user/:id/todo => Create todo for user

To get the list of users, the GET /user can return this response:

{
  "users": [
    {
      "id": "user1",
      "name": "Bob"
    },
    {
      "id": "user2",
      "name": "Joe"
    }
  ]
}

Then to get the todos for the first user, a GET /user/user1/todo can return this:

{
  "todos": [
    {
      "name": "todo1",
      "checked": false
    },
    {
      "name": "todo2",
      "checked": true
    }
  ]
}

Following the REST approach gives a good idea what is possible with the API just by looking at the verb + path pairs. It's easy to see what objects are available just by seeing their names in the paths, and the hierarchy among them. In the above example, todo items are part of users, which is evident from the /user/:id/todo path.

On the other hand, nothing enforces a REST-like API to follow these conventions, it's entirely up to the developer (or the designer of the API) to make it easy for others to understand the structure. Also, there is no built-in way to document a REST API. To do that, you'll need to rely on other projects, for example, OpenAPI.

Queries in REST are HTTP requests to the API endpoint. Usually, a query returns one object (/user/:id) or a list (/user) and any referenced objects need a separate request (/user/:id, then /user/:id/todo).

What is GraphQL

GraphQL is based on graphs. There are nodes, that are similar to objects in REST, and edges between them. In our previous example we had users and todos, and a connection between a user and a todo is that a todo belongs to a user.

In the above data model, the user objects have a todos field and the todo items are referenced through that field. You can think of it as a label on the edge that distinguishes how the objects are connected. For example, let's say users can have friends and blocked users. In that case, two users can be connected in two ways: friend or blocked.

This is visualized like this:

Also, edges are directed. A user might block another user but that might not be mutual.

Queries in GraphQL define the whole structure the requester needs. For example, a single query might get a user object and all todos for that user. Or, in a more complex example, a query might get a user, its latest posts, its friends, and their latest posts too.