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

GET /catsGET /cats/7POST /catsDEL /cats/7
one noun, four verbs: the whole CRUD surface of /cats

key terms

endpoint

One address for one resource. Method plus path tells the server exactly which door you knocked on.

GET /api/cats/7

idempotent

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 delete

stateless

The server keeps no memory between requests. Every ask carries everything needed to answer it.

token in every header

4xx vs 5xx

Client-side failure versus server-side failure. The first digit tells you whose bug it is.

401 yours, 500 mine

how it works

  1. 1
    Name the nouns

    Plural, lowercase, no verbs: /users, /users/42, /users/42/orders. The URL is a filing system.

  2. 2
    Attach the verbs

    GET reads, POST creates, PUT replaces, PATCH edits, DELETE removes. The method does the talking.

  3. 3
    Pick honest statuses

    201 for created, 404 for missing, 400 for a bad ask. The status code is your API's tone of voice.

  4. 4
    Return shaped JSON

    Consistent field names, errors with a message. The client should never have to guess.

  5. 5
    Version 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

1app.get('/cats', listCats)
same path as below, different method, different job
2app.get('/cats/:id', oneCat)
the colon is a parameter: any id lands in req.params
3app.post('/cats', newCat)
4app.put('/cats/:id', saveCat)
5app.delete('/cats/:id', byeCat)
same noun again — the verb changes the meaning

side by side

REST style

  • GET /users/42
  • verbs live in the method
  • one mental model everywhere
  • caches and tools just work
VS

RPC style

  • POST /getUser?id=42
  • verb baked into the URL
  • every endpoint is ad hoc
  • one new name per action
🪤 gotcha

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

🎤 interview

Which methods can you safely retry?watch ↗

🎤 interview

401 vs 403?watch ↗

🎤 interview

The status codes you actually shipwatch ↗

📚 tutorial

How do you name endpoints?watch ↗

🔧 useful

Your list endpoint will die without thiswatch ↗

💎 deep

Breaking changes without breaking apps?watch ↗

🆕 update

REST or GraphQL?watch ↗

🧠 trivia

HTTP 418 is realwatch ↗