Stop 01 · Internet & Backend BasicsTopics · 9/15

REST Principles

In short

REST is a set of habits for designing APIs so they feel predictable. Learn them once and you can guess how most APIs work just by reading their URLs.

An architectural style for designing APIs around resources and standard HTTP methods, with a uniform, predictable interface — the dominant API style in the industry.

The mascot librarian pulls a book from neatly ordered shelves while a student waits at the counter.

Think of it like this

The library catalogue

Every book has its own call number, so you find it on any visit. The rules are the same at every shelf: look, borrow, return. And the librarian doesn't need to remember you, your card says it all. REST APIs work the same way.

Watch it happen

Resources as a tree of URLs

/api

/users

/users/42

/users/42/orders

/products

/products/7

1/5Everything hangs off one base path. Each path below it is a resource: a noun, not an action.

The big ideas

What you need to know

Nouns in URLs, verbs in methods

Write POST /orders, not POST /createOrder. The HTTP method already says what you want to do.

Stateless requests

Each request carries its own auth and inputs. The server doesn't rely on what you sent before.

Standard codes and formats

Use normal status codes and a consistent JSON shape, so clients can handle every endpoint the same way.

Query strings for options

Filtering, sorting and paging go in the query: GET /orders?status=paid&page=2.

See it in code

Walk through the code

1import { Router } from "express";2 3const users = Router();4 5users.get("/", listUsers);            // GET    /api/users?page=26users.post("/", createUser);          // POST   /api/users7users.get("/:id", getUser);           // GET    /api/users/428users.patch("/:id", updateUser);      // PATCH  /api/users/429users.delete("/:id", deleteUser);     // DELETE /api/users/4210users.get("/:id/orders", listOrders); // GET    /api/users/42/orders11 12app.use("/api/users", users);

1/4The collection: list users or create a new one.

listUsers and the rest are your handler functions. Notice there's no /getUsers or /deleteUser anywhere: the method carries the verb.

Save yourself the pain

Common mistakes

Oops

Verb URLs like POST /createOrder and GET /getAllOrders.

Do this instead

Use nouns: POST /orders and GET /orders. Let the method be the verb.

Oops

Returning a different user shape from /users/42 than from /users.

Do this instead

Keep one consistent JSON shape per resource, whether it comes alone or inside a list.

Your mission

Clean up a messy API

~20 min

Quick check

Which is the most RESTful way to fetch all paid orders of user 42?

Go deeper

1Design a REST API for a resource (e.g. `/users`) following proper conventions.
2Learn the 6 REST constraints: client-server, stateless, cacheable, uniform interface, layered system, code-on-demand.
3Critique a poorly designed API you've used and identify what breaks REST conventions.