GraphQL API vs REST API

The main differences between REST and GraphQL and when it's best to use one vs the other

Since REST is such a popular approach to building APIs, and much more widespread than GraphQL, it’s fair to assume you are familiar with it, so let’s see the differences between GraphQL and REST.

Rest is a concept

REST is a de-facto architecture standard but it actually has no specification and tons of unofficial definitions. GraphQL has a specification draft, and it’s a Query Language instead of an architecture, with a well defined set of tools built around it (and a flourishing ecosystem).

While REST is built on top of an existing architecture, which in the most common scenarios is HTTP, GraphQL on the other hand is building its own set of conventions. Which can be an advantage point or not, since REST benefits for free by caching on the HTTP layer.

A single endpoint

GraphQL has only one endpoint, where you send all your queries. With a REST approach, you create multiple endpoints and use HTTP verbs to distinguish read actions (GET) and write actions (POST, PUT, DELETE). GraphQL does not use HTTP verbs to determine the request type.

Tailored to your needs

With REST, you generally cannot choose what the server returns back to you, unless the server implements partial responses using sparse fieldsets, and clients use that feature. The API maintainer cannot enforce such filtering.

The API will usually return you much more information than what you need, unless you control the API server as well, and you tailor your responses for each different request.

With GraphQL you explicitly request just the information you need, you don’t “opt out” from the full response default, but it’s mandatory to pick the fields you want.

This helps saving resources on the server, since you most probably need less processing, and also network savings, since the payload to transfer is smaller.

A great way to visualize this is an example of a Pizza endpoint (I’m Italian, a Pizza example is perfect).

If you call GET /pizza/margherita, you will get the a pizza Margherita. If you call GET /pizza/napoli, you will get a pizza Napoli.

If you have 30 different flavors, you’ll have 30 endpoints (unless you pass the pizza name as a parameter to GET /pizza, for example)

But maybe you want a specific kind of pizza, but without one ingredient you don’t like. That’s easy to ask to the waiter, but kinda hard to express to a REST endpoint.

A GraphQL endpoint would let you call /pizza, and you ask for specific ingredients, to build the perfect pizza you want.

GraphQL makes it easy to monitor for fields usage

With REST usually there is no way to determine if a field is needed by the client, so when it comes to refactoring or deprecating, it’s impossible to determine actual usage.

GraphQL makes it possible to track which fields are used by clients.

Access nested data resources

GraphQL allows to generate a lot less network calls.

Let’s do an example: you need to access the names of the friends of a person. If your REST API exposes a /person endpoint, which returns a person object with a list of friends, you generally first get the person information by doing GET /person/1, which contains a list of ID of its friends.

Unless the list of friends of a person already contains the friend name, with 100 friends you’d need to do 101 HTTP requests to the /person endpoint, which is a huge time cost, and also a resource intensive operation.

With GraphQL, you need only one request, which asks for the names of the friends of a person.

Types

A REST API is based on JSON which cannot provide type control. GraphQL has a Type System.

Which one is better?

Organizations around the world are questioning their API technology choices and they are trying to find out if migrating from REST to GraphQL is best for their needs.

GraphQL is a perfect fit when you need to expose complex data representations, and when clients might need only a subset of the data, or they regularly perform nested queries to get the data they need.

As with programming languages, there is no single winner, it all depends on your needs.

Also, there’s a point I want to make: you can use both.

You can mix and match REST and GraphQL depending on your needs, and sometimes it’s the best thing to do.