You speak HTTP. Now let's see what happens when teams agree to use it consistently. REST isn't a technology — it's a discipline. Most "REST APIs" out there break the rules. Time to learn which ones matter, and design one yourself.
Look at any API documentation in the wild and you'll see a war between two styles. On one side: action-based URLs — every operation gets its own URL with a verb in the path. On the other: resource-based URLs — the URL identifies a thing, and the HTTP method describes what to do with it. The second style is REST. Compare:
Same six operations, two completely different design philosophies. The left side invents a new endpoint for every action. The right side has just two URLs (/users and /users/42) — and uses HTTP's existing verbs to do all the work. That's the entire idea of REST in one screen. Everything else is just rules for keeping the discipline.
REST stands for Representational State Transfer — a name that has scared off generations of developers. Ignore the name. Here's the actual idea:
users, posts, orders, payments. Always nouns, never verbs./users. A specific user is /users/42. The posts owned by user 42 are /users/42/posts.GET reads. POST creates. PUT replaces. DELETE removes. PATCH modifies.Once you internalize this, every "should I name this endpoint /createUser or /users?" debate dissolves. The answer is always POST /users. The URL identifies the resource (the user collection); the method says what to do (create one). Designing an API becomes a question of "what are my resources?" instead of "what are all the actions my client needs to do?"
"CRUD" — Create, Read, Update, Delete — is the most common set of operations any system needs. REST maps these directly to HTTP methods, and the URL pattern is mechanical. Memorize this table; you'll see it everywhere.
?page=2&limit=20). Read-only.{ "title": "..." } only changes the title.That's it. Two URL patterns — collection (/posts) and item (/posts/42) — combined with five HTTP methods. From these primitives, you can express almost any CRUD-style operation in any system. The nesting (/posts/42/comments) is just the same pattern applied recursively.
You're building the backend for a small blog platform. For each operation below, pick the most RESTful URL design. You'll get instant feedback on every choice — and at the end, see the complete API you built.
Anyone reading this API can predict every endpoint.
The original REST paper has six "constraints." In practice, these five carry their weight every day. Internalize them and your APIs will be predictable, scalable, and pleasant to use.
Never put a verb in the URL. /users, not /getUsers. /orders/42/cancel is a yellow flag — could you model it as PATCH /orders/42 with {"status":"cancelled"} instead? Sometimes the verb is unavoidable, but the default should always be a noun.
Every request carries everything the server needs to handle it — auth, params, body. The server doesn't remember anything between requests. This is what lets you put a load balancer in front and have any server handle any request. We'll go deep in Module 13.
2xx for success, 4xx for client errors, 5xx for server errors. Don't return 200 with {"error": "..."} in the body. The status code IS the result. Lying about it breaks every monitoring tool, retry logic, and CDN policy that depends on HTTP working as advertised.
Pick a style and stick with it. Plural nouns (/users, not /user). Lowercase. Kebab-case for multi-word (/blog-posts). Whatever you choose, apply it everywhere. Inconsistency is more painful than the wrong choice.
Once an API has clients, breaking it breaks them. Put a version in the URL (/v1/users) or in a header. When you need to break something, ship v2 and deprecate v1 gracefully. Without versioning, you can never evolve safely.
The original REST paper says responses should include links to related resources ("here's the user, and here's the URL for their posts"). In practice, almost no APIs do this. Know it exists, know what it means, then carry on without losing sleep.
These rules aren't laws — they're conventions that make APIs predictable. Predictability is the entire point. When someone reads GET /orders/42/items, they should be able to guess that POST /orders/42/items creates a new item and DELETE /orders/42/items/7 removes one. That guessability is REST's real superpower.
You'll hear these in every API design review for the rest of your career. Learn them well enough that you can challenge people who misuse them.
users, posts, orders. Each resource gets a URL. Always a noun./posts is a collection. /posts/42 is one item. GET on a collection returns the list; POST creates a new item.GET /users/42 is an endpoint. DELETE /users/42 is a different endpoint.POST, GET, PUT/PATCH, and DELETE.?page=2&limit=20 or cursor-based. Never return an unbounded list — that's an outage waiting to happen./v1/... in the path. Lets you ship breaking changes without breaking existing clients.You've designed an API. Now lock in the principles behind it.
Phase A is officially yours. Time to look under the hood at data.
You've completed Phase A. Carry these into everything that follows.
URLs identify things; HTTP methods describe what to do with them. POST /users, not /createUser. This single flip cleans up most API design debates.
List = GET collection. Read = GET item. Create = POST collection. Replace = PUT item. Modify = PATCH item. Delete = DELETE item. Memorize.
If a developer can guess your endpoints without reading the docs, you've succeeded. Consistency, honest status codes, and stateless requests are how you get there.