Part 8 of 9 · 4 min read
Choosing between REST, gRPC and GraphQL
What each style gains and costs, with one screen as a worked case.
Choosing between REST, gRPC and GraphQL
Think of three ways to order food. One is a fixed menu with set plates (REST). One is a private phone line between the kitchen and the shop next door, fast and strict (gRPC). One is a form where the guest ticks the exact ingredients wanted (GraphQL).
REST fits public APIs. Every browser and tool can call it. Responses can be cached by URL. Its weakness is that the shape of each reply is fixed by the server. A mobile screen may need three fields from a resource that has twelve. This is called over-fetching. A screen may also need data from three resources, which means three calls. This is called under-fetching.
gRPC fits calls between services. It sends Protocol Buffers over HTTP/2, a newer form of HTTP that carries many requests on one connection at the same time. The schema is written once in a file, and code for several languages is generated from it. Messages are small, and the schema gives strong checks. Its weaknesses are that browsers cannot call it directly without help, and that people cannot read the messages by eye.
GraphQL fits clients with many different screens. The book "Understanding Distributed Systems" describes a graph-based API as one that exposes types, fields and relations. The client states which data it needs, and a gateway turns that into calls to the internal services. This reduces the need for a different API for each screen.
GraphQL
GraphQL is a query language for APIs. The caller sends a query that names the exact fields it wants, and the server returns those fields and no others.
Example: the query { product(id: 42) { name price } } returns only the name and the price of product 42.
A worked case. A product screen on a phone needs the name, the price and the first 3 reviews. The round trip to the server is 150 milliseconds. The numbers are made up.
- REST, calls in turn:
GET /products/42(150 ms), thenGET /products/42/reviews?limit=3(150 ms). The total is 300 ms. A third call for the seller adds another 150 ms. If the calls are independent, the client can send them together and wait about 150 ms, but must handle three replies and three possible failures. - GraphQL, one call: one query names the product fields and the 3 reviews. The total is about 150 ms plus the server's work.
- Size: if the REST product reply has 12 fields and 2,000 bytes, and the screen needs 2 fields of about 100 bytes, then 95 percent of the bytes are unused (1,900 ÷ 2,000). On a slow mobile link, that matters.
GraphQL has costs too. A query can ask for a great deal of data, so the server needs limits on query depth and size. Caching by URL is harder, since every request is a POST to one endpoint. The server code that joins data from many places is more complex.
| Question | Leaning |
|---|---|
| Public, many unknown callers | REST |
| Internal service to service, high volume | gRPC |
| Many screens, mobile, varied data needs | GraphQL |
| Needs caching by URL | REST |
| Needs strict schema and generated code | gRPC |
Most real systems mix them: GraphQL or REST at the edge, gRPC inside.
Interview angle
Answer in your head first, then open it.
What are the first calls you would define for a design?
Name the two or three main resources, give each a URL and a method, say which calls need an idempotency key, and say how the list calls are paged.
A payment request times out. What does the client do?
Retry with the same idempotency key, with a growing pause, so the charge happens once.
Offset or cursor?
Offset for small lists and jumping to pages. Cursor for large or changing lists, because the cost stays flat and rows do not repeat.
How do you change an API that has old clients?
Add compatible fields first. For a break, add a new version beside the old one, and switch the old one off after the traffic fades.
Check yourself:
- What is over-fetching, and which style reduces it?
- Why is gRPC a better fit between services than for a public website?
Words you will meet
| Word | Plain meaning |
|---|---|
| API | The operations a service offers and the shape of each request and reply |
| Client, server | The sender of a request, and the receiver that answers |
| Serialization | Turning data in memory into bytes to send or save |
| RPC | A call to another machine that looks like a local call |
| Resource | A thing an API talks about, with its own URL |
| REST | HTTP conventions: resource URLs, method as action |
| Safe | Changes nothing visible |
| Idempotent | Many repeats leave the same end state as one |
| Idempotency key | A client-chosen value that makes a repeat return the saved result |
| Pagination | Returning a long list in pieces |
| Cursor | A marker for where the last page ended |
| Backward compatible | Old callers still work after the change |
| GraphQL | A query language where the caller names the fields it wants |