Choosing between REST, GraphQL, and gRPC

None of the last three lessons' technologies is a strictly better version of the others — each one was built by optimizing for a specific situation, and the choice that fits one part of a system is often the wrong choice for a different part of that same system.

Intermediate

3 min read

Restating each one's actual bet

REST (System Design's foundational lessons, and lesson 1's maturity model) bets on ubiquity and simplicity: plain HTTP, human-readable JSON, cacheable by generic infrastructure that understands nothing about the specific API, using standard verbs and status codes almost every developer already knows.
GraphQL (lessons 4-5) bets on client-driven flexibility: exactly the fields a specific screen needs, across however many related resources, in one round trip — at the cost of a more complex server implementation (resolvers, the N+1 problem) and a different caching model than REST's simple per-URL caching.
gRPC (lesson 6) bets on raw performance between trusted, tightly coupled services: binary payloads, generated strongly-typed clients, and native streaming — at the cost of browser-friendliness and human-readable debugging.

The question that actually decides it: who's calling, and why

Rather than "which technology is best," the more useful question is "who's the primary consumer of this specific API, and what do they actually need from it":

A public API meant for third-party developers (a payments API, a platform integration) almost always wants REST — the ubiquity and predictability matter more than any efficiency gain, since third-party developers need to integrate with minimal friction using tools they already know.
A team's own frontend, rendering several related, differently-shaped views of overlapping data (a dashboard pulling from many resources at once) is exactly GraphQL's strongest case — it directly solves the over/under-fetching problem lesson 4 opened with.
Internal microservices calling each other at high volume, especially where strict typing and streaming matter, is gRPC's strongest case — the browser-friendliness gRPC gives up simply isn't needed for service-to- service traffic in the first place.

A single real system often uses all three at once

It's entirely normal — common, even, at real scale — for one company's architecture to expose a public REST API to partners, serve its own web app through a GraphQL layer that aggregates several backend services into client-friendly shapes, while those backend services talk to each other over gRPC internally. Choosing one technology as "the API layer" for an entire company is usually the wrong framing; the right framing is choosing per boundary, based on who's actually on the other side of that specific boundary.

The cost of switching later

Once an API has real external consumers — the same "cost of change" theme from System Design's versioning lesson — switching from REST to GraphQL (or vice versa) for a public-facing API is a genuinely large migration, not a quick refactor: it usually means running both in parallel during a long transition, not a clean swap. This is a real argument for thinking carefully about the primary consumer before building the first version, rather than treating the initial choice as easily reversible later.

Why "just use GraphQL for everything" is a common, costly mistake

GraphQL's flexibility looks universally appealing on paper, but a public API with graph-shaped free-form queries is harder to rate-limit predictably (a single query can be arbitrarily expensive depending on how deeply it's nested) and harder to cache with simple, generic infrastructure than a REST API's fixed set of URLs. Teams that adopt GraphQL everywhere by default, rather than for the specific case it's strongest at, often end up re-implementing REST-like restrictions (query complexity limits, persisted queries) on top of GraphQL just to get back the predictability REST gave them for free.

Choosing between REST, GraphQL, and gRPC

Intermediate

3 min read

Restating each one's actual bet

REST (System Design's foundational lessons, and lesson 1's maturity model) bets on ubiquity and simplicity: plain HTTP, human-readable JSON, cacheable by generic infrastructure that understands nothing about the specific API, using standard verbs and status codes almost every developer already knows.
GraphQL (lessons 4-5) bets on client-driven flexibility: exactly the fields a specific screen needs, across however many related resources, in one round trip — at the cost of a more complex server implementation (resolvers, the N+1 problem) and a different caching model than REST's simple per-URL caching.
gRPC (lesson 6) bets on raw performance between trusted, tightly coupled services: binary payloads, generated strongly-typed clients, and native streaming — at the cost of browser-friendliness and human-readable debugging.

The question that actually decides it: who's calling, and why

Rather than "which technology is best," the more useful question is "who's the primary consumer of this specific API, and what do they actually need from it":

A public API meant for third-party developers (a payments API, a platform integration) almost always wants REST — the ubiquity and predictability matter more than any efficiency gain, since third-party developers need to integrate with minimal friction using tools they already know.
A team's own frontend, rendering several related, differently-shaped views of overlapping data (a dashboard pulling from many resources at once) is exactly GraphQL's strongest case — it directly solves the over/under-fetching problem lesson 4 opened with.
Internal microservices calling each other at high volume, especially where strict typing and streaming matter, is gRPC's strongest case — the browser-friendliness gRPC gives up simply isn't needed for service-to- service traffic in the first place.

Choosing between REST, GraphQL, and gRPC

Restating each one's actual bet

The question that actually decides it: who's calling, and why

A single real system often uses all three at once

The cost of switching later

Why "just use GraphQL for everything" is a common, costly mistake

Further reading

Choosing between REST, GraphQL, and gRPC

Restating each one's actual bet

The question that actually decides it: who's calling, and why

A single real system often uses all three at once

The cost of switching later

Why "just use GraphQL for everything" is a common, costly mistake

Further reading