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%
mobile appREST APIREST APIGraphQLone endpointGraphQLUsersserviceUsersPostsservicePostsHTTPS + JSONGET /users/42GET /users/42/postsGET /users/42/followersThe profile with RESTGET /users/4222 KBGET /users/42/posts30 KBGET /users/42/followers8 KB3 calls in a row60 KBexample valuesloading…4G · 100 ms per round tripWhat the screen usesname and photo≈ 0.5 KB3 latest posts≈ 3.2 KBfollower count≈ 0.3 KB60 KB arrive≈ 4 KB used4G · 100 ms per round tripOne single query{ user(id: 42) { name avatarUrl posts(first: 3) { title } followerCount } }1 trip · ≈ 4 KB · only what was asked≈ 45,000 lookups98 %A «small» query{ user(id: 42) { followers { followers { posts { title } }≈ 45,000 lookups150 + 22,500 profiles and 22,500 listsgRPCgRPC30 %25 %A gRPC contractservice Posts { rpc ListPosts (PostsQuery) returns (PostList);}binary · typed · smaller than JSON3,000,000 followersfollowers · page 1,501after: "c81e", first: 2030 %25 %Paging a long listoffset 30000, limit 20reads 30,020 rowsafter c81e, limit 20index, reads 20every response carries the next cursorapp 4.1 · closesname → fullNamegRPCgRPC30 %25 %Change without breakingremove or rename a fieldbreaks old appsadd a fieldbreaks nothingdeprecate and measureremove laterbreaking? /v2 next to /v1GraphQLgRPCgRPC30 %25 %Where each one fitsRESTpublic APIs, CRUDmany callsGraphQLmany clientscostly queriesgRPCbetween servicesnot in browsersGraphQLgRPCgRPC30 %25 %
  • 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.

You will learn

  • See an API as a contract
  • Design resources and verbs with REST
  • Ask only for the fields you need with GraphQL
  • Connect internal services with RPC
  • Paginate long lists and evolve an API without breaking it