REST APIs
- Pradeep P
- 3 days ago
- 3 min read
Series: Modern System Design · Layer 2 — Communication
Layer 2 · Post 1 of 10
Layer 2 — Communication · Post 16 of 88
REST is a way to expose resources over HTTP with nouns, verbs, and status codes. It is the most common public API style on the internet.
What you'll learn
What "REST" actually promises, versus what most APIs do in practice
Resources, verbs, status codes, and why they matter at the other end of the wire
When REST is the right default — and when it starts to hurt
The idea in one minute
REST (Representational State Transfer) is a style for building APIs over HTTP.
You model the world as resources (things with names and URLs), not as a pile of remote function calls. You act on those resources with HTTP methods:
GET /orders/42 — read
POST /orders — create
PUT / PATCH /orders/42 — replace or update
DELETE /orders/42 — remove
The response is a representation (usually JSON) plus a status code (200, 201, 404, 409). Clients that know HTTP already know a lot about your API.
Most REST APIs are really HTTP + JSON + resource-ish URLs. That is still a good default for public internet APIs.
Why it matters
Layer 1 was boxes. Layer 2 is how the boxes talk.
REST is the dialect browsers, mobile apps, and partner integrations already speak. It is cacheable (GET can sit behind a CDN), inspectable (you can curl it), and boring in the best way.
It is also easy to do poorly: verbs in URLs (/getOrder), POST for everything, 200 with an error in the JSON body. Those APIs still work. They throw away the parts of HTTP that load balancers, caches, and clients were built to use.
How it works
Resources, not RPC
RPC says call createOrder(user, items). REST says there is an orders collection; POST a new one.
The URL is the identity. /users/9/orders is orders belonging to user 9. Query strings filter (?status=paid). Path params identify.
Status codes are a contract
Code: 200; Meaning in practice: Here is the thing
Code: 201; Meaning in practice: Created; often with a Location header
Code: 204; Meaning in practice: Done, no body
Code: 400; Meaning in practice: Your request is malformed
Code: 401 / 403; Meaning in practice: Auth / permission
Code: 404; Meaning in practice: No such resource
Code: 409; Meaning in practice: Conflict (duplicate, wrong version)
Code: 429; Meaning in practice: Slow down (rate limit)
Code: 5xx; Meaning in practice: Our problem
Clients should branch on these. Hiding every failure as 200 with error true makes retries and monitoring harder.
Idempotency (preview)
GET, PUT, and DELETE are supposed to be safe to repeat. POST is not — two POSTs can create two orders. That is why payment APIs add idempotency keys (Layer 3).
Versioning
Common patterns: /v1/orders in the path, or a header. Path versions are visible and cache-friendly. Do not break existing clients for a rename.
A simple example
A notes API:
GET /notes — list (paginated)
GET /notes/abc — one note
POST /notes — JSON body → 201 + the new note
PATCH /notes/abc — change title
DELETE /notes/abc — 204
A mobile app, a website, and a curl script can all use the same contract. A CDN can cache GET /notes/abc if you set Cache-Control (and if the note is public).
Common mistakes
Chatty APIs. Twenty GETs to render one screen. That is a latency problem from Layer 1. Fix with coarser resources, a BFF, or GraphQL — not with more REST purity.
Verbs in paths. /doCreateOrder is RPC wearing a URL. Use nouns and methods.
No pagination. GET /events returning 2 million rows will take you down. Cursor or page from day one if the list can grow.
Treating REST as a religion. Internal service-to-service calls at high QPS often prefer gRPC (next post). REST is the public front door more often than the internal bus.
How this shows up in real systems
Stripe, GitHub, Twilio: public REST (or REST-ish) HTTP APIs with careful status codes and versioning.
Your own backend: the API gateway from Layer 1 terminates TLS and routes /v1/* to services that speak HTTP.
OpenAPI / Swagger: the usual way to document and generate clients.
In a design interview, we'll expose a REST API is the default. Say which resources, how they are identified, and what is cached.
Recap
REST maps resources to HTTP URLs and methods, with status codes as part of the contract.
It is the default for public APIs because the web already knows HTTP.
Keep URLs as nouns, use codes honestly, and do not make clients chat.
Internal services sometimes want something denser than JSON-over-HTTP. That is gRPC.
Series: Modern System Design · Layer 2 — Communication
Layer 2 · Post 1 of 10
Comments