REST, RPC and GraphQL
- Lesson 20 of 40
- 11 min
- Beginner
- 10 steps
Your app needs data that lives on your servers. How it asks decides how many trips it makes, how many bytes it pulls and what breaks when the API changes.
- Trips per screen
- 1
- KB downloaded
- 4
- Screen ready
- 125 ms
- Unused data
- 0%
- request
- response
- slow request
- waiting in queue
Step 1 of 10
Concept
Two programs need an agreement
Your mobile app opens a profile screen: name, photo, the three latest posts and how many followers there are. That data sits on your servers, so the app has to ask for it.
An API is the agreement on how to ask: which addresses exist, what you send and what shape the answer has. Here it travels as JSON over HTTPS.
Step 2 of 10
Technique
REST: addressable resources and HTTP verbs
REST arranges data as resources with their own URL (/users/42, /users/42/posts) and applies HTTP verbs to them: GET reads, POST creates, PUT or PATCH modify and DELETE removes.
Every tool understands it, and browsers and CDNs can cache GET responses. GET, PUT and DELETE are also idempotent: repeating them leaves the same result. POST is not, and that matters when the client retries.
On a fast network (≈ 40 ms per round trip, plus ≈ 20 ms of server time per call) the screen takes 3 × 60 = 180 ms. The figures in this lesson are example values.
What changed
- Three endpoints for the profile screen
Step 3 of 10
Problem
Too many trips and too many bytes
On a phone each round trip costs about 100 ms. The app makes its three calls in a row, often because one needs a value from the previous answer: 3 × (100 + 20) = 360 ms before anything is drawn.
And each endpoint returns the whole object: 60 KB arrive to show about 4 KB, so 93 % goes unused. Getting more than you need is over-fetching; needing several calls for one screen is under-fetching.
What changed
- Network: 4G, ≈ 100 ms per round trip
- Screen ready: 180 → 360 ms
- 93 % of the download goes unused
Step 4 of 10
Solution
GraphQL: describe the exact shape you want
With GraphQL the app sends one query that lists the fields it needs. The GraphQL server spreads the work across the services behind it and returns only those fields.
Follow the packet: it leaves the phone, splits towards Users and Posts in parallel and comes back as a single answer. One 100 ms trip plus ≈ 40 ms on the server: 140 ms and ≈ 4 KB.
What changed
- REST API → GraphQL endpoint
- Users and Posts services behind it
- 3 trips → 1
- 60 KB → 4 KB
Step 5 of 10
Trade-off
A flexible query can get very expensive
The client may ask for anything the schema allows, including followers of followers with their posts. At 150 followers each that is 150 + 22,500 profiles and 22,500 post lists: about 45,000 lookups for a single request.
Queries also usually go as POST to one URL, so HTTP caches and CDNs cannot help without extra work such as persisted queries.
What changed
- A query nested three levels deep
- Users service at 98 %
Step 6 of 10
Technique
Inside the data center: RPC
Behind the API, services call each other all the time. There the usual choice is RPC (remote procedure call): invoking a function on another machine as if it were local. Today that is often gRPC.
The contract is a typed schema in Protocol Buffers; client and server code are generated from it, and messages travel as compact binary over HTTP/2. In the example, internal calls drop from ≈ 40 to ≈ 25 ms: 100 + 25 = 125 ms.
What changed
- API → services: gRPC + Protocol Buffers
Step 7 of 10
Technique
Case: a list of 3 million
A famous account has 3 million followers. At about 100 bytes per follower, returning them all at once would be ≈ 300 MB. Long lists are served in pages.
With offset=30000 and limit=20 (page 1,501), the database reads and throws away 30,000 rows before handing over the 20 you asked for. With a cursor («the 20 after c81e») it jumps straight there through the index, and it neither repeats nor skips items when new followers arrive.
What changed
- Followers 20 at a time
- Cursor pagination
Step 8 of 10
Problem
Case: renaming a field breaks old apps
Someone tidies the schema and renames name to fullName. The new app works, but thousands of phones still run version 4.1, and their profile screen closes when name is missing.
You cannot force anyone to update. So APIs grow by adding: add the new field, keep the old one and retire it once almost nobody uses it. GraphQL marks it with @deprecated; in REST a breaking change goes into a new version (/v2) that lives next to /v1.
What changed
- Old apps close
- Fix: keep name and add fullName
- /v2 for breaking changes
Step 9 of 10
Trade-off
Which one, and where?
The panel sums up where each style fits and what to watch. They do not compete: they combine.
The usual setup is REST or GraphQL facing out, for apps and clients, and gRPC facing in, between services.
Step 10 of 10
Summary
Recap
An API is a contract between programs.
REST: resources and HTTP verbs; simple and cacheable, but many calls for rich screens.
GraphQL: one query with the exact fields; limit depth and cost.
gRPC: fast, typed calls between internal services.
Paginate long lists with cursors and grow the API by adding, without breaking.
← → step · R replay · Space pause
You will learn
- See an API as a contract (covered)
- Design resources and verbs with REST (covered)
- Ask only for the fields you need with GraphQL (covered)
- Connect internal services with RPC (covered)
- Paginate long lists and evolve an API without breaking it (covered)