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:
- Who decides what comes back, the server or the caller?
- How many round trips does a job take?
- 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.
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.
The job: show a profile screen with a user's name and the titles of their two latest posts.
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.
The same job: a user's name and the titles of their two latest posts.
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.
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.
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
| REST | GraphQL | gRPC | |
|---|---|---|---|
| Who shapes the answer | The server | The caller | The contract |
| Round trips for a rich screen | Several | One | One per call |
| Message format | Text (JSON) | Text (JSON) | Binary |
| Contract | Optional | Required schema | Required, checked at build time |
| Web caching | Works naturally | Needs extra effort | Not through web caches |
| Called from a browser | Yes | Yes | Only through a proxy |
| Streaming | Not built in | Subscriptions | Built in |
Which one should you use?
Start from who is calling.
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.