These are the notes for System Design episode 18. In episode 17 ChaiNow became services that talk over the network. Today: how should they talk? Every team invents its own URLs, so you'll invent REST: resources, HTTP methods and status codes. A phone screen then needs four requests and gets six times more data than it shows, so you'll invent GraphQL. Inside the backend, a typo in one service crashes another team's service, and text JSON is wasteful, so you'll invent gRPC: a shared .proto contract, generated code and binary Protocol Buffers over HTTP/2. Every demo is plain Python and runs as-is; outputs are real (Python 3.13). resolve() is a tiny GraphQL-style teaching version, not the real GraphQL library; the hand-written binary encoder produces exactly the bytes the real protobuf library produces (checked with protobuf 7.36.1).
The problems
| Problem | What it teaches |
|---|---|
| Every team's URLs look different | APIs; REST resources, URLs, HTTP methods, status codes, statelessness |
| One screen needs 4 requests | Under-fetching, round trips |
| 539 bytes sent, 88 needed | Over-fetching; GraphQL queries, schema, resolvers |
| A typo crashes another team's service | Loose JSON vs a shared contract (schema, IDL) |
| Text is big between services | Binary encoding, Protocol Buffers, varints, gRPC, HTTP/2 |
| Which one, when? | REST for public APIs, GraphQL for flexible clients, gRPC inside |
Problem 1: every team's URLs look different
An API (application programming interface) is how one program asks another for something. At ChaiNow, each team made up its own style:
| Team | Endpoint |
|---|---|
| Orders | /getOrder?id=7 |
| Support | /cancel_order/7 |
| Another team | /removeOrder |
A new developer guesses /getorder?id=7 and gets 404 Not Found. Nobody can guess anything; every team's docs must be read every time.
The fix: REST
The library rule: every book has an address (shelf 7, row 2), there are only a few actions (borrow, return) that work on every book, and you show your card every time because the librarian remembers nothing.
| REST idea | Meaning | Example |
|---|---|---|
| Resource | A thing the API manages, named by a noun | an order |
| URL / URI | The resource's address | /orders (the collection), /orders/7 (one order) |
| HTTP method | The verb: what to do with it | GET read, POST create, PUT/PATCH change, DELETE remove |
| Status code | A number saying what happened | 200, 201, 204, 404, 405 |
| Stateless | Each request carries everything needed (e.g. the login token); the server keeps no session | any server behind the load balancer (episode 6) can answer |
| Representation | The format the resource is sent in | JSON |
REST, short for representational state transfer, "was introduced and defined in 2000 by computer scientist Roy Fielding in his doctoral dissertation" (Wikipedia, "REST").
Demo 1: a tiny REST handler
orders = {7: {"item": "chai", "qty": 2}}
def handle(method, path, body=None):
parts = path.strip("/").split("/") # "/orders/7" -> ["orders", "7"]
if parts[0] != "orders":
return 404, {"error": "no such resource"}
if len(parts) == 1: # the collection: /orders
if method == "GET": return 200, orders
if method == "POST":
new_id = max(orders) + 1
orders[new_id] = body
return 201, {"id": new_id}
else: # one order: /orders/7
oid = int(parts[1])
if oid not in orders: return 404, {"error": f"order {oid} not found"}
if method == "GET": return 200, orders[oid]
if method == "DELETE": del orders[oid]; return 204, None
return 405, {"error": f"{method} not allowed here"}
print(handle("GET", "/orders/7"))
print(handle("POST", "/orders", {"item": "samosa", "qty": 1}))
print(handle("DELETE", "/orders/7"))
print(handle("GET", "/orders/7"))
print(handle("PUT", "/orders"))
Output:
(200, {'item': 'chai', 'qty': 2})
(201, {'id': 8})
(204, None)
(404, {'error': 'order 7 not found'})
(405, {'error': 'PUT not allowed here'})
| Code | Name | Meaning |
|---|---|---|
| 200 | OK | Here's what you asked for |
| 201 | Created | A new resource was made (often with its id or URL) |
| 204 | No Content | Done, nothing to send back |
| 404 | Not Found | That resource doesn't exist |
| 405 | Method Not Allowed | The resource exists, but not that method |
The CRUD operations (create, read, update, delete) map onto POST, GET, PUT/PATCH, DELETE. PUT replaces a whole resource; PATCH changes some fields.
Problem 2: one screen, too many requests
The home screen shows Asha's name and the items of her last orders. With REST: GET /users/1, then GET /orders/<id> for each order.
import json
users = {1: {"id": 1, "name": "Asha", "phone": "98xxxxxx01", "email": "asha@mail.in",
"address": "12 MG Road, Pune", "joined": "2024-03-01", "orders": [7, 8, 9]}}
orders = {i: {"id": i, "item": it, "qty": 1, "price": 20, "status": "delivered",
"shop": "Chai Point", "rider": "Ravi", "paid_by": "UPI"}
for i, it in [(7, "chai"), (8, "samosa"), (9, "vada pav")]}
calls = sent = 0
def GET(path): # every REST call returns the whole resource
global calls, sent
kind, rid = path.strip("/").split("/")
data = (users if kind == "users" else orders)[int(rid)]
calls += 1; sent += len(json.dumps(data))
return data
# the home screen: Asha's name + the items of her orders
user = GET("/users/1")
items = [GET(f"/orders/{o}")["item"] for o in user["orders"]]
print("screen:", user["name"], items)
print(f"REST: {calls} requests, {sent} bytes sent")
screen = {"name": user["name"], "orders": [{"item": i} for i in items]}
print(f"needed: {len(json.dumps(screen))} bytes")
Output:
screen: Asha ['chai', 'samosa', 'vada pav']
REST: 4 requests, 539 bytes sent
needed: 88 bytes
- Under-fetching: one call doesn't return enough, so you need more calls (4 round trips on a slow phone network). With N orders this is the "1 + N requests" pattern.
- Over-fetching: each call returns fields the screen never shows (539 bytes for 88 used).
Adding a special endpoint per screen (phone, tablet, web) doesn't scale either.
The fix: GraphQL
A REST resource is a fixed thali: the kitchen decides the plate. GraphQL is writing your own order slip, and one waiter brings it all.
graphql.org: "GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data." Clients "receive just that data in the expected shape with a single request".
The client sends a query, the shape of the data it wants:
{
user(id: 1) {
name
orders { item }
}
}
Demo 3: a tiny GraphQL-style resolver
import json
users = {1: {"id": 1, "name": "Asha", "phone": "98xxxxxx01", "email": "asha@mail.in",
"address": "12 MG Road, Pune", "joined": "2024-03-01", "orders": [7, 8, 9]}}
orders = {i: {"id": i, "item": it, "qty": 1, "price": 20, "status": "delivered",
"shop": "Chai Point", "rider": "Ravi", "paid_by": "UPI"}
for i, it in [(7, "chai"), (8, "samosa"), (9, "vada pav")]}
def resolve(obj, fields): # walk the query; keep only what was asked
out = {}
for f, sub in fields.items():
val = obj[f]
if f == "orders":
val = [resolve(orders[o], sub) for o in val]
out[f] = val
return out
# the client sends the SHAPE it wants, in one request:
# { user(id: 1) { name orders { item } } }
query = {"name": {}, "orders": {"item": {}}}
answer = resolve(users[1], query)
print(json.dumps(answer, indent=1))
print(f"GraphQL-style: 1 request, {len(json.dumps(answer))} bytes")
Output:
{
"name": "Asha",
"orders": [
{
"item": "chai"
},
{
"item": "samosa"
},
{
"item": "vada pav"
}
]
}
GraphQL-style: 1 request, 88 bytes
(It's printed with indent=1 to read easily; the 88 bytes are the compact JSON.)
A resolver is the server function that produces one field's value. The extra lookups still happen, but on the server, next to the data, not over the phone's network.
GraphQL's price
| Strength | Cost |
|---|---|
| One request, exactly the fields, typed schema checked on every query | Usually one URL, often POST, so plain HTTP/URL caching (episodes 7-8) is harder |
| Each screen asks for its own shape | A client can send a huge, deep query; servers limit depth and cost |
Problem 3: services talking to services
Orders calls points thousands of times a second with JSON agreed in a chat message. One day the orders team writes amout.
import json
def points_server(body): # the points team's service
data = json.loads(body) # text in, parse it
return f"added {data['amount'] // 10} points"
print(points_server('{"user_id": 1001, "amount": 35}'))
print(points_server('{"user_id": 1001, "amout": 35}')) # orders team's typo
Output:
added 3 points
Traceback (most recent call last):
File "main.py", line 8, in <module>
print(points_server('{"user_id": 1001, "amout": 35}')) # orders team's typo
~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "main.py", line 5, in points_server
return f"added {data['amount'] // 10} points"
~~~~^^^^^^^^^^
KeyError: 'amount'
The mistake was the orders team's, but the crash is on the points team's server, in production. Nothing checked the message against an agreed shape, and JSON repeats every field name as text in every message.
The fix: a shared contract, binary messages, gRPC
Both teams share one .proto file, the contract (an IDL, interface definition language):
syntax = "proto3";
message PointsRequest {
int32 user_id = 1;
int32 amount = 2;
}
message PointsReply {
int32 added = 1;
}
service Points {
rpc AddPoints (PointsRequest) returns (PointsReply);
}
From grpc.io: "a client application can directly call a method on a server application on a different machine as if it were a local object" (a remote procedure call, RPC); the contract is "an ordinary text file with a .proto extension"; "gRPC uses protoc with a special gRPC plugin to generate code from your proto file". Protocol Buffers are both the IDL and the message format.
Demo 5: the contract and the binary encoding, by hand
import json
from dataclasses import dataclass
@dataclass
class PointsRequest: # the contract: field 1 user_id, field 2 amount
user_id: int
amount: int
def varint(n): # 7 bits per byte; top bit = "more bytes follow"
out = b""
while n > 0x7F:
out += bytes([n & 0x7F | 0x80]); n >>= 7
return out + bytes([n])
def encode(r): # [field number + type] [value], no names sent
return bytes([1 << 3]) + varint(r.user_id) + bytes([2 << 3]) + varint(r.amount)
req = PointsRequest(user_id=1001, amount=35)
as_json = json.dumps({"user_id": req.user_id, "amount": req.amount}).encode()
print("JSON: ", len(as_json), "bytes", as_json)
print("binary:", len(encode(req)), "bytes", encode(req).hex(" "))
print(PointsRequest(user_id=1001, amout=35)) # the same typo
Output:
JSON: 31 bytes b'{"user_id": 1001, "amount": 35}'
binary: 5 bytes 08 e9 07 10 23
Traceback (most recent call last):
File "main.py", line 23, in <module>
print(PointsRequest(user_id=1001, amout=35)) # the same typo
~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: PointsRequest.__init__() got an unexpected keyword argument 'amout'. Did you mean 'amount'?
Reading the 5 bytes:
| Bytes | Meaning |
|---|---|
08 |
field 1, wire type 0 (varint): 1 << 3 \| 0 |
e9 07 |
1001 as a varint: low 7 bits 0x69 + "more" bit = 0xe9, then 1001 >> 7 = 7 |
10 |
field 2, wire type 0: 2 << 3 \| 0 |
23 |
35 (fits in 7 bits, one byte) |
The real protobuf library (code generated by protoc from the .proto above) produces exactly 08 e9 07 10 23, and its version of the typo fails at the caller too: ValueError: Protocol message PointsRequest has no "amout" field.
gRPC = the .proto contract + generated client and server code + Protocol Buffers on the wire + HTTP/2. Google's announcement (26 Feb 2015) calls it "based on the recently finalized HTTP/2 standard", Protocol Buffers "a high performance, open source binary serialization protocol", and lists "bidirectional streaming" among HTTP/2's capabilities.
Which one, when?
| REST | GraphQL | gRPC | |
|---|---|---|---|
| Best for | Public and partner APIs | Apps with many screens needing different data | Service-to-service calls inside your system |
| Shape decided by | The server (fixed resources) | The client (query) | The shared .proto contract |
| Format | Usually JSON text | JSON text | Binary Protocol Buffers |
| Transport | HTTP | HTTP (usually one endpoint) | HTTP/2 |
| Strengths | Simple, any tool (even curl), HTTP caching |
One request, exact fields, typed schema | Small, fast, typed, generated code, streaming |
| Weaknesses | Over/under-fetching | Caching harder, costly queries | Not human-readable; needs the generated code on both sides |
Many companies use all three: gRPC inside, REST or GraphQL at the edge.
The whole chain
- Everyone's URLs differed → REST: nouns in URLs, verbs as HTTP methods.
- Status codes say what happened: 200, 201, 204, 404, 405.
- One screen: 4 requests, 539 bytes for 88 needed (under- and over-fetching).
- GraphQL: the client sends the shape; 1 request, 88 bytes.
- A typo crashed another team's service → a shared contract.
- gRPC:
.proto, generated code, binary Protocol Buffers (5 bytes vs 31), HTTP/2.
Common mistakes (and the real errors)
| Mistake | Code | Error / result | Fix |
|---|---|---|---|
| Verbs in the URL | POST /deleteOrder?id=7 |
nobody can guess your API | DELETE /orders/7 |
| Wrong status codes | 200 with {"error": ...} |
clients think it worked | Use 404, 405, 429... |
| Loose JSON between services | data['amount'] with "amout" sent |
KeyError: 'amount' on the receiver |
A shared schema (.proto) |
| Typo with a contract (the good case) | PointsRequest(user_id=1001, amout=35) |
TypeError: ... unexpected keyword argument 'amout'. Did you mean 'amount'? |
Fix the field name |
| Unlimited GraphQL queries | orders → user → orders → ... | very expensive queries | Depth and cost limits |
| Reusing a protobuf field number for a new meaning | int32 amount = 1; |
old clients misread messages | Never reuse numbers; add new ones |
Mini project: a tiny GraphQL-style server with a schema and a depth limit
# Mini project: a tiny GraphQL-style server with a schema check and a depth limit
SCHEMA = {"User": {"name": None, "phone": None, "orders": "Order"},
"Order": {"item": None, "price": None, "user": "User"}}
users = {1: {"name": "Asha", "phone": "98xxxxxx01", "orders": [7, 8]}}
orders = {7: {"item": "chai", "price": 20, "user": 1},
8: {"item": "samosa", "price": 15, "user": 1}}
MAX_DEPTH = 3
def check(type_name, fields, depth=1): # validate BEFORE running
if depth > MAX_DEPTH:
raise ValueError(f"query is deeper than {MAX_DEPTH} levels")
for f, sub in fields.items():
if f not in SCHEMA[type_name]:
raise ValueError(f'no field "{f}" on type {type_name}')
inner = SCHEMA[type_name][f]
if inner:
check(inner, sub, depth + 1)
def resolve(type_name, obj, fields):
out = {}
for f, sub in fields.items():
inner, val = SCHEMA[type_name][f], obj[f]
if inner == "Order": val = [resolve("Order", orders[o], sub) for o in val]
if inner == "User": val = resolve("User", users[val], sub)
out[f] = val
return out
def query(fields):
try:
check("User", fields)
return {"data": resolve("User", users[1], fields)}
except ValueError as e:
return {"errors": [str(e)]}
print(query({"name": {}, "orders": {"item": {}}}))
print(query({"nmae": {}}))
print(query({"orders": {"user": {"orders": {"user": {"name": {}}}}}}))
Output:
{'data': {'name': 'Asha', 'orders': [{'item': 'chai'}, {'item': 'samosa'}]}}
{'errors': ['no field "nmae" on type User']}
{'errors': ['query is deeper than 3 levels']}
Like real GraphQL servers, it checks every query against the schema before running it, and answers with data or errors. (The error texts here are this demo's own, not the real library's.) Extend it: give each field a cost and reject queries whose total cost is too high.
Practice
- Homework: add
PATCH /orders/<id>to Demo 1 to change some fields. Try it on order 7 and on order 99. - Homework: in Demo 3, also ask for each order's
price. How many bytes now? - Homework: in Demo 5, encode
amount=300. How many bytes does the varint take, and why? - Design REST URLs and methods for: list a shop's menu, add a dish, change a dish's price, remove a dish.
- Which would you choose: (a) a public API for restaurant partners, (b) the Android app's 15 different screens, (c) the payments service calling the fraud-check service 5,000 times a second?
- Why does "stateless" make scaling out easier?
Solutions and hints
1. Add if method == "PATCH": orders[oid].update(body); return 200, orders[oid] after the DELETE line:
(200, {'item': 'chai', 'qty': 3})
(404, {'error': 'order 99 not found'})
2. query = {"name": {}, "orders": {"item": {}, "price": {}}}:
the answer now has an item and a price in each order, and the last line is:
GraphQL-style: 1 request, 127 bytes
Still one request; the screen decided to ask for more.
3. binary: 6 bytes 08 e9 07 10 ac 02 (JSON: 32 bytes). 300 needs 9 bits, more than the 7 a varint byte carries: ac = low 7 bits (44) + the "more" bit, 02 = 300 >> 7. The real protobuf library gives the same bytes.
4. GET /shops/{shopId}/dishes, POST /shops/{shopId}/dishes, PATCH /shops/{shopId}/dishes/{dishId} with {"price": 30}, DELETE /shops/{shopId}/dishes/{dishId}.
5. (a) REST: simple for outsiders, any language, cacheable. (b) GraphQL: each screen asks for its own shape. (c) gRPC: high volume, small binary messages, a strict contract between your own teams.
6. No server keeps a client's session, so any server can answer any request; the load balancer can send each request anywhere, and servers can be added or removed freely.
Quick quiz
# REST API for ChaiNow
# order 42 was never created
GET /orders/42
# what status code comes back?
- A. 200 OK
- B. 201 Created
- C. 404 Not Found
- D. 405 Method Not Allowed
Answer
C. The resource doesn't exist: 404. 405 would mean the resource exists but that method isn't allowed on it.
Interview questions
- What makes an API RESTful? (Resources named by URLs, standard HTTP methods, status codes, stateless requests.)
PUTvsPATCH? (Replace the whole resource vs change some fields.)- What are over-fetching and under-fetching? (Too much data per call vs too many calls per screen.)
- How does GraphQL solve them, and what does it cost? (Client-shaped queries in one request; harder caching, expensive queries need limits.)
- Why is gRPC popular between microservices? (Shared contract, generated code, compact binary Protocol Buffers, HTTP/2 streaming.)
- How do you evolve a protobuf message safely? (Add new fields with new numbers; never reuse or change existing numbers.)
- Which status code for "too many requests"? (429, next episode.)
Glossary
| Term | Meaning |
|---|---|
| API | Application programming interface: how one program asks another for something |
| Endpoint | One URL (plus method) an API answers on |
| REST | Representational state transfer: resources, URLs, HTTP methods, status codes, statelessness (Fielding, 2000) |
| Resource | A thing the API manages, named by a noun (an order) |
| URL / URI | The address of a resource (/orders/7) |
| Collection | A resource holding many items (/orders) |
| HTTP method | The verb of a request: GET, POST, PUT, PATCH, DELETE |
| CRUD | Create, read, update, delete |
| Status code | A number in every HTTP response saying what happened (200, 404...) |
| Stateless | Each request carries all it needs; the server keeps no session between requests |
| Representation | The format a resource is sent in (JSON) |
| JSON | JavaScript Object Notation: a text format for data |
| Round trip | A request going to the server and its reply coming back |
| Under-fetching | One call doesn't return enough, so more calls are needed |
| Over-fetching | A call returns more data than the client uses |
| GraphQL | A query language for APIs where the client asks for exactly the fields it needs |
| Query (GraphQL) | The shape of the data the client wants |
| Schema | The types and fields an API offers; every request is checked against it |
| Resolver | The server function that produces one field's value |
| Contract | A shared, exact description of messages both sides must follow |
| IDL | Interface definition language: a language for writing contracts (.proto) |
| RPC | Remote procedure call: calling a function on another machine as if it were local |
| gRPC | Google's open-source RPC framework: .proto contracts, generated code, Protocol Buffers, HTTP/2 |
| Protocol Buffers (protobuf) | Google's binary serialization format and IDL |
.proto file |
The text file that defines protobuf messages and gRPC services |
protoc |
The protobuf compiler that generates code from .proto files |
| Serialization | Turning data into bytes to send or store (and back: deserialization) |
| Binary encoding | Sending data as compact bytes instead of readable text |
| Varint | A variable-length integer: 7 bits per byte, the top bit means "more bytes follow" |
| Field number | The number protobuf sends instead of the field's name |
| HTTP/2 | A newer version of HTTP with binary framing, many streams on one connection, and streaming |
| Streaming | Sending a sequence of messages over one call instead of one request and one reply |
@dataclass |
Python decorator that builds a class with typed fields and a checking __init__ |
Summary
- REST: name resources with URLs (nouns), act with HTTP methods (verbs), answer with status codes, keep requests stateless. The default for public APIs.
- REST's fixed shapes cause under-fetching (4 requests) and over-fetching (539 bytes for 88).
- GraphQL lets the client send the shape it needs: one request, exact fields, a typed schema; but caching is harder and queries need limits.
- Loose JSON between services pushes errors onto the receiver (
KeyError: 'amount'). - gRPC shares a
.protocontract, generates code that catches typos at the caller, and sends compact binary Protocol Buffers (5 bytes vs 31) over HTTP/2.
Next episode: our API is public. What happens when one buggy script sends it a million requests? Rate limiting.
Sources: Wikipedia, "REST"; graphql.org, "Introduction to GraphQL" (docs); grpc.io, "Introduction to gRPC"; Google Developers Blog, "Introducing gRPC, a new open source HTTP/2 RPC Framework" (26 Feb 2015).