REST APIs
The waiter of the internet: takes orders, never cooks.
▶ the lesson · narrated sketch video · tap for sound
the intro
A REST API is how two programs talk over HTTP. The client sends a request to an endpoint, the server answers with data, usually JSON. The verbs are the vocabulary: GET reads, POST creates, PUT updates, DELETE removes. That is ninety percent of the job.
the sample
the classic request
GET /api/memes?sort=votes
HTTP/1.1 200 OK
[
{ "id": 1, "funny": true }
]fun fact ✦
REST was Roy Fielding’s doctoral homework in 2000. Best. Homework. Ever.
the docs
the deep dive
the ideas behind the video — concepts, diagrams, a walkthrough and the traps to avoid
REST has no installer and no framework. It is a handshake of conventions riding on plain HTTP: URLs name things, methods say what you are doing to them, and status codes report how it went. Learn the conventions once and you can guess your way around almost every API on the internet.
nouns in URLs, verbs in methods
key terms
endpoint
One address for one resource. Method plus path tells the server exactly which door you knocked on.
GET /api/cats/7idempotent
Safe to repeat. Doing it twice leaves the same state as once, which is true for GET, PUT, and DELETE but never POST.
DELETE twice = 1 deletestateless
The server keeps no memory between requests. Every ask carries everything needed to answer it.
token in every header4xx vs 5xx
Client-side failure versus server-side failure. The first digit tells you whose bug it is.
401 yours, 500 minehow it works
- 1Name the nouns
Plural, lowercase, no verbs: /users, /users/42, /users/42/orders. The URL is a filing system.
- 2Attach the verbs
GET reads, POST creates, PUT replaces, PATCH edits, DELETE removes. The method does the talking.
- 3Pick honest statuses
201 for created, 404 for missing, 400 for a bad ask. The status code is your API's tone of voice.
- 4Return shaped JSON
Consistent field names, errors with a message. The client should never have to guess.
- 5Version it early
/v1/ costs nothing on day one and saves you the day v2 must break something.
the code, explained
the entire REST surface of /cats in Express
side by side
REST style
- GET /users/42
- verbs live in the method
- one mental model everywhere
- caches and tools just work
RPC style
- POST /getUser?id=42
- verb baked into the URL
- every endpoint is ad hoc
- one new name per action
POST is not idempotent, and retries are everywhere: the user double-clicks Buy, the mobile app retries on flaky train wifi, your queue redelivers, and you charge twice. Guard money-touching POSTs with an idempotency key.
quick answers
Is REST dying?
No. GraphQL and gRPC solve real problems like over-fetching and service-to-service latency, but REST is still the default for public APIs and it caches beautifully.
Can a GET request have a body?
Technically possible, practically no: most servers and proxies ignore it. Put filters in query params instead, like /cats?sort=age.
What makes an API truly RESTful?
Academic REST adds hypermedia links (HATEOAS). Almost nobody ships that. Pragmatic REST, meaning nouns plus verbs plus statuses, is the industry version and it is fine.
quick hits about REST APIs
short answers · interviews, tips, trivia & hidden gems
Which methods can you safely retry?watch ↗
401 vs 403?watch ↗
The status codes you actually shipwatch ↗
How do you name endpoints?watch ↗
Your list endpoint will die without thiswatch ↗
Breaking changes without breaking apps?watch ↗
REST or GraphQL?watch ↗
HTTP 418 is realwatch ↗