Why REST APIs Alone Are Not Enough at Scale

REST has dominated API design since the early 2000s, but relying on it exclusively creates real problems at scale. This video breaks down the history of API paradigms, the specific limitations of REST, the promise and complexity of GraphQL, and why most serious products end up using a mix of approaches.

A Brief History of API Paradigms

RPC dominated the API scene from the 1970s through the early 1990s. Then came CORBA, followed by Microsoft's DCOM, then XML-RPC, then SOAP. REST took over in the early 2000s and has held the top spot since. GraphQL arrived in 2015, gRPC in 2016, but neither has fully displaced REST. There are good reasons for that persistence, and good reasons to look beyond it.

The Problems with REST

REST is easy to build because it maps naturally onto web application patterns. But it carries a set of well-known limitations:

Overfetching and underfetching. REST endpoints return fixed data shapes. You often get more data than you need, or you need to make multiple calls to assemble what you actually want.

The N+1 problem. If you are building a mobile app and need order details for a list of users, you first fetch the users, then make a separate call for each user's orders, and potentially more calls for order details. The number of round trips grows fast.

Versioning complexity. You can use headers, query parameters, or URL paths, but none of these approaches are simple in practice. Deprecating old endpoints is difficult.

Documentation and contracts. REST does not enforce strict contracts between client and server. Keeping documentation accurate requires discipline and tooling.

GraphQL: Not a Free Lunch

GraphQL was supposed to fix many of these problems. It gives you a schema definition language and a query language so clients can request exactly the data they need without resource-based endpoint constraints.

But adopting GraphQL changes your architecture significantly. Instead of a simple three-tier setup (client, server, storage), you now need a GraphQL proxy, one or more GraphQL servers, and those servers still need to connect to data sources or backend API endpoints. The operational overhead is substantial.

GraphQL also introduces its own set of problems. Caching becomes complex because queries are freeform. File uploads have no built-in solution. Rate limiting is difficult because you need to compute the cost of each query rather than simply counting API calls.

The Practical Answer: Mix and Match

Each API paradigm has advantages and disadvantages within different contexts. REST is easy to build and works well for straightforward CRUD operations. GraphQL shines when clients need flexible data access. gRPC is strong for internal service-to-service communication where performance matters.

For any sufficiently large or popular product, you will likely end up using a combination of REST, GraphQL, and gRPC to get the best performance and developer experience across different parts of your platform.

Key Takeaways

• REST is easy to implement but struggles with overfetching, underfetching, the N+1 problem, and versioning at scale
• GraphQL solves some of REST's data-fetching problems but adds significant architectural complexity and its own set of challenges
• Most production systems at scale use a mix of REST, GraphQL, and gRPC, chosen based on the specific needs of each part of the system

Resources

• glich.stream -- YouTube channel with practical system design content
• GraphQL -- Official GraphQL specification and documentation
• gRPC -- Google's high-performance RPC framework