REST vs GraphQL — (Will GraphQL do to REST what XML did to JSON)?

After working with REST APIs over past few years, I came to know about GraphQL and the problems it’s attempting to solve, I could not wait posting this article.

What is What?

REST is an architectural approach to creating web services. GraphQL is a query language for designing APIs. Both are used to create web services allowing clients to communicate with remote servers over HTTP.

So, you might be wondering what is the difference between the two or what new thing GraphQL has to offer that makes it worth discussion. Let me illustrate it with a use-case:

“Imagine you are at the checkout page of a transaction and obviously you would want the checkout to happen as fast as possible. On payment page, your application would send the checkout details to the server and wait for the response. The response time depends upon the size of the response object returned by the API. More the size of the response object, more time it takes to receive the response. And if you have slower internet connection, then may be you would feel even frustrated waiting for the transaction to finish”.

What Graph QL does?

“You Get exactly What you Ask for” and not everything that is there.

What you seek is what you Get

One of the main reasons why GraphQL is preferred to REST is the precision with which data is retrieved from the server.

REST:

A core concept behind REST is the idea of resources. A resource represents a piece of data you want to retrieve from the server. If your web app is a blog then resources may include posts, comments, count of likes, users, etc.

Each resource is identified by a URL. You fetch a given resource by sending a HTTP request that may look something like this:

/users/<userid>/posts

The server processes your request and returns something like this:

{
  "posts": [
    {
      "title":"My latest post",
      "author":"Sameer",
      "likes":13
    },
    {
      "title":"My other post",
      "author":"Amit",
      "likes":4
    },
    {
      "title":"My last post",
      "author":"Varun",
      "likes":32
    }
  ]
}

For a user with a given <userid>, the service returns a JSON object with an array of post objects.

GraphQL:

GraphQL also uses the same HTTP protocol to retrieve information from the server, but it leverages a type system defined in a schema. So, you formulate the request object with what u want and you would get the precise response.

Now Let’s see how GraphQL would implement the same REST call from the previous example:

query {
  User(userid: <userid>) {
    posts {
      title,
      author,
      likes
    }
  }
}

The server processes the request and returns:

{
  "posts": [
    {
      "title":"My latest post",
      "author":"Sameer",
      "likes":13
    },
    {
      "title":"My other post",
      "author":"Amit",
      "likes":4
    },
    {
      "title":"My last post",
      "author":"Varun",
      "likes":32
    }
  ]
}

Notice how the exact same JSON response is returned using GraphQL…

Wondering what GraphQL did that REST couldn’t do?

While our basic /users/<userid>/posts endpoint gave us the data we needed, it may have given us more than we asked for.

Overfetching: What if we only wanted the title of the posts to be returned?

This is known as “overfetching” since we got back more than we asked for. Specifically, we got back the author and likes along with the title.

Underfetching: Another scenario could be that you need some more information about each post. In addition to likes, authors, and titles you may also want the number of comments for a given post, etc. This is called as “underfetching” and results in additional requests needed for each post object being returned.

Now, you may be thinking….so what? After all, you could modify the REST endpoint to accept parameters for each field you want returned or create a new endpoint all together.

This would require more development work and more coordination across different teams.

Alternatively, with GraphQL we could simply modify our original query to address the “overfetching” problem:

query {
  User(userid: <userid>) {
    posts {
      title
    }
  }
}

or the “underfetching” problem:

query {
  User(userid: <userid>) {
    posts {
      title,
      author,
      likes,
      followers
    }
  }
}

Notice how in both cases we simply add or subtract fields that we want returned. Remember GraphQL uses the same API endpoint for every query…so no need to bug the API team.

Pros and Cons of REST and GraphQL:

REST pros:

• widely accepted- REST has been around since 2000 and remains one of the most popular approaches to implementing web services today.
• caching — REST inherently supports caching much better than GraphQL. This makes for better performance out of the box.
• reusable — using REST, you can more easily develop independent microservices that work independently of one another. Microservices are (ideally) fully decoupled from clients allowing for them to be accessed by multiple applications.

REST cons:

• excessive round trips — more endpoints requires more requests. We saw how the problem of underfetching can lead to excessive requests over the network.
• overfetching — downloading unnecessary data
• underfetching — not retrieving enough data, resulting in additional requests
• coordination efforts — This is one of the cons which even i have faced numerous times coordinating with the endpoint team and it’s more difficult to develop front ends independently of back ends since new requirements require new endpoints (or modification of existing endpoints).

GraphQL pros:

• schema — by defining a schema with types of data and queries, GraphQL creates a contract between the client and the server making the data available to the client more obvious. Front end developers don’t need to concern themselves with back end.
• easy to get started — you don’t have to be an expert with web service architecture to start producing / consuming GraphQL.
• precision — you can retrieve exactly the data you’re looking for without additional endpoints or modification of those endpoints. GraphQL more efficiently addresses the overfetching/underfetching problem.

GraphQL cons:

• scalability issues — GraphQL is easy to get started with, but can become more of a performance issue as complex queries surface and grow.
• schema limitations — With GraphQL, you’re stuck with the schema that’s defined. This can cause headaches when you want more in-depth responses than provided.
• still fairly new — GraphQL is still considered the new kid on the block. So very few implementations at present. May increase over time.

Conclusion:

Both invovle sending HTTP requests and receiving data from a server. Both have the idea of resources and can specify IDs for those resources. Both can return JSON responses.

Answering the question as to which is better for you really depends on the dynamic between different dev teams in your organization. If you already follow a microservice architecture, then dropping REST to play with GraphQL may not be the best idea. However if your team emphasizes rapid API development driven by the front end, then GraphQL may be the best fit for you.

Secondly, the way JSON superseeded use of XMLs due to numerous advantages it offers but that didn’t kill XML. It is still in use. Same way, GraphQL might not kill the existing REST over the coming years.