Choosing REST or GraphQL

You should use GraphQL over REST when your application needs flexibility in what it fetches, has nested data relationships, and has to reduce the amount of data sent over the network to different kinds of clients.

GraphQL was created to solve two inefficiencies of REST: over-fetching, getting more data than you need, and under-fetching, not getting enough data and having to make several round trips.

Under-fetching revisited

If your user interface needs to display a page of related data all at once, REST typically leads you either to make several requests in sequence or to build endpoints that are specific to one page and return more than most clients need.

With GraphQL, you can fetch a parent, its children, and deeply nested resources in one request to one endpoint. For example, suppose we want to build a dashboard for our shop, and suppose a later version of the shop’s API includes user profiles, order histories, product recommendations, and shipment tracking. A single GraphQL query can fetch the user, their last five orders, the tracking status of each order, and the recommended products at once.

Over-fetching revisited

In REST, the server often returns more data than the client needs. This is a particular problem for phone apps and other clients with limited bandwidth. When you have web apps, iOS apps, Android apps, and other clients all served by the same backend, what each one needs to display varies a great deal.

With GraphQL, the client names the exact fields it needs. The server returns only those, which reduces the amount of data sent over the network and speeds up page loads.

Even with a single client, a frontend team can redesign a screen, or change the data it requests, without waiting for the backend team to change an endpoint.

When to stay with REST

REST is still the industry standard for straightforward, resource-based CRUD applications. If you are building one of those, stay with REST, especially when a fixed set of representations covers what the clients need. If every client reads the same few representations, there is no over-fetching or under-fetching to fix.

REST has its own advantages. It uses standard HTTP features, such as HTTP caching. Its API design is simple, with no query language to learn. And it has well-established tooling and libraries.