CSE Roadmap

Core tier · about 3 hours · 9 parts

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), then GET /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