Pointer Walk

REST, gRPC or GraphQL

Three ways for programs to talk. Who calls it, how many round trips, and how strict the contract needs to be.

System DesignBeginner9 min read

Three ways for programs to talk

An API is how one program asks another for something. A mobile app asks a server for a user's profile. One backend service asks another to charge a card.

There are three popular styles for designing that conversation: REST, GraphQL and gRPC. They all run over the same network. They differ on three questions:

  1. Who decides what comes back, the server or the caller?
  2. How many round trips does a job take?
  3. How strict is the contract between the two sides?

Try it first

Pick a style and step through it. Count the arrows: each pair is one round trip across the network.

RESTInteractive
Style
Mobile app
API server

The job: show a profile screen with a user's name and the titles of their two latest posts.

REST

Every thing has an address, and you act on it with a small set of verbs.

A user is at /users/42. That user's posts are at /users/42/posts. You GET to read, POST to create, PUT or PATCH to change, DELETE to remove. The answer is usually JSON, and its shape is fixed by the server.

RESTInteractive
Mobile app
API server

The job: show a profile screen with a user's name and the titles of their two latest posts.

http
GET /users/42 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "name": "Ada", "email": "ada@example.com", "bio": "..." }

Two things in the animation are typical of REST. The app received more than it needed, which is called over-fetching. And it needed a second request for the related data, which is called under-fetching.

Good at

  • Familiar to every developer, and every language and tool can call it
  • Easy to try in a browser or from the command line
  • Works with the web's built-in caching, because each address has one answer

Where it bites

  • Screens that need several kinds of data make several round trips
  • Answers often carry fields the caller does not need
  • The contract is only as strict as your documentation

GraphQL

The caller describes the shape of the data it wants, and gets exactly that.

There is a single address. The server publishes a schema: a list of every type and field that exists. The app sends a query that picks fields from it, including fields of related things, all in one request.

GraphQLInteractive
Mobile app
API server

The same job: a user's name and the titles of their two latest posts.

graphql
query {
  user(id: 42) {
    name
    posts(last: 2) {
      title
    }
  }
}

One round trip, and nothing extra in the answer. That matters most on a phone with a slow connection, and for teams whose screens change every week: a new screen needs a new query, not a new endpoint.

The work has not disappeared. It has moved to the server, which now has to answer queries it has never seen before.

Good at

  • One round trip for a whole screen
  • No over-fetching: the answer has only the fields asked for
  • The schema is a precise, checkable contract

Where it bites

  • Caching is harder: one address, and every query is different
  • A caller can write a very expensive query, so the server needs limits
  • Naive servers do one database lookup per item, which adds up quickly

gRPC

Calling another service looks like calling a function.

You write the contract first, in a small file that lists the functions and the exact shape of their inputs and outputs. From that file, tools generate code for both sides, in whatever languages you use.

protobuf
service Users {
  rpc GetUser (GetUserRequest) returns (User);
  rpc WatchUser (GetUserRequest) returns (stream User);
}

message GetUserRequest { int64 id = 1; }
message User { int64 id = 1; string name = 2; }

Messages travel as compact binary instead of text, and a call can stay open so that either side can keep sending. That is streaming.

gRPCInteractive
Orders service
Users service

A different setting: one of your backend services needs data from another.

Good at

  • Small, fast messages
  • The strictest contract: a mismatch is caught when the code is built
  • Streaming in either direction, or both

Where it bites

  • Browsers cannot call it directly, so it needs a proxy for web apps
  • Binary messages cannot be read by eye when debugging
  • Both sides must share the contract file and regenerate when it changes

Side by side

RESTGraphQLgRPC
Who shapes the answerThe serverThe callerThe contract
Round trips for a rich screenSeveralOneOne per call
Message formatText (JSON)Text (JSON)Binary
ContractOptionalRequired schemaRequired, checked at build time
Web cachingWorks naturallyNeeds extra effortNot through web caches
Called from a browserYesYesOnly through a proxy
StreamingNot built inSubscriptionsBuilt in

Which one should you use?

Start from who is calling.

REST, gRPC or GraphQL?Interactive

Who will call this API?

Many companies use more than one: REST for the public API, GraphQL for their own apps, gRPC between services.

Key takeaways

  • REST gives every thing an address. It is the most familiar and the easiest to cache.
  • GraphQL lets the caller ask for exactly the data a screen needs, in one round trip.
  • gRPC makes service-to-service calls fast, strictly typed, and able to stream.
  • The first question is who calls the API: the public, your own apps, or your own services.
  • Mixing them is normal. Pick per use, not per company.

Your progress

Check your progress

0%

  1. Read the page50% of this page

    When you have gone through the page and its animations, tick it off.

  2. Take the quiz50% of this page

    7 questions, from easy to hard. Take it as often as you like: the questions change, and only your best score counts.

Saved on this device only. See all your progress