REST Conventions and Resource Design
The conventions real REST APIs follow for URLs and HTTP methods, and how to spot when an API breaks its own conventions.
What you'll learn
- Map CRUD operations to conventional REST HTTP methods and URL patterns
- Identify a URL or method choice that breaks REST convention
- Explain why consistent conventions make an API easier to test
Prerequisites
Explanation
A REST API models data as resources, addressed by URLs, manipulated with standard HTTP methods. Once you know the convention, you can often predict an unfamiliar API's shape correctly before reading its documentation — and just as usefully, you can immediately spot when an API violates its own conventions, which is itself worth testing for.
The standard mapping, using a "tasks" resource as an example:
- GET /tasks — list all tasks
- GET /tasks/42 — retrieve one specific task
- POST /tasks — create a new task (the server usually assigns the id and returns it)
- PUT /tasks/42 — replace task 42 entirely with the given data
- PATCH /tasks/42 — partially update task 42 (only the fields provided)
- DELETE /tasks/42 — delete task 42
Two distinctions matter for testing specifically. PUT vs. PATCH: PUT should replace the entire resource — send a PUT with only one field and, done correctly, every other field should revert to its default or be required; PATCH updates only what's provided, leaving everything else untouched. A tester who doesn't know this distinction can't tell whether "the other fields got wiped out" is a bug (if it was a PATCH) or correct behavior (if it was a PUT).
Nesting reveals relationships: GET /users/7/orders conventionally means "the orders belonging to user 7" — a resource nested under its parent. If an API instead exposes this same data at a completely unrelated-looking URL like /getUserOrderData?uid=7, that's a convention break worth flagging, not because it won't work, but because it makes the API harder to predict, harder to document consistently, and more error-prone for every client that integrates with it.
Conventions aren't a rule enforced by the HTTP protocol itself — nothing stops an API from using GET to delete something. That's exactly why testing for convention violations matters: they're not caught by "does it technically work," only by someone deliberately checking whether the API behaves the way its own shape implies it should.
Example
A simulated REST-style router mapping methods and paths to actions — a compact way to reason about (and test) an API's conventions before touching a real server.
const routes = {
"GET /tasks": "list all tasks",
"GET /tasks/:id": "get one task",
"POST /tasks": "create a task",
"PUT /tasks/:id": "replace a task",
"PATCH /tasks/:id": "partially update a task",
"DELETE /tasks/:id": "delete a task",
};
console.log(routes["GET /tasks/:id"]);
console.log(routes["PATCH /tasks/:id"]);Try it yourself
Add a route for listing a specific user's tasks nested under that user, then log it.
Code editor. Press Escape then Tab to leave the editor if keyboard focus becomes trapped. Press Control+Shift+M inside the editor to toggle Tab-key focus trapping.
Guided exercise
Guided exercise
Write a function conventionalMethod(action) that maps 'list', 'create', 'replace', 'partial-update', 'delete' to the correct HTTP method string ('GET', 'POST', 'PUT', 'PATCH', 'DELETE').
Checks: list maps to GET · create maps to POST · partial-update maps to PATCH · delete maps to DELETE
Code editor. Press Escape then Tab to leave the editor if keyboard focus becomes trapped. Press Control+Shift+M inside the editor to toggle Tab-key focus trapping.
Stuck? Get a hint.
Independent exercise
Independent exercise
Write a function isConventionalUrl(method, url) that returns true for these conventional patterns and false otherwise: GET /resources, GET /resources/123 (any numeric id), POST /resources, DELETE /resources/123. Anything else (e.g. a verb in the URL like /getResource) is false.
Checks: GET on a collection URL is conventional · GET on an item URL is conventional · a verb-based URL is correctly flagged as unconventional · DELETE on an item URL is conventional
Code editor. Press Escape then Tab to leave the editor if keyboard focus becomes trapped. Press Control+Shift+M inside the editor to toggle Tab-key focus trapping.
Stuck? Get a hint.
Common mistakes
- Assuming PUT and PATCH are interchangeable — sending a PUT with a partial payload can silently wipe out fields that weren't included.
- Not testing whether an API's actual behavior matches what its URL/method combination implies (does DELETE really only delete the one specified resource?).
- Missing that resource nesting (like /users/7/orders) implies an ownership/scoping relationship worth specifically testing (does it only return that user's orders, never another user's?).
Knowledge check
Takeaway
REST conventions map CRUD operations to predictable HTTP methods and URL patterns — knowing them lets you predict an API's shape and, just as importantly, spot when it breaks its own rules.
Summary
This lesson covered the conventional REST mapping of list/create/replace/partial-update/delete to HTTP methods and URLs, and why convention violations are worth testing for even when the endpoint technically works.
References
Your notes
Notes save automatically.
Finished this lesson?
Mark it complete to track your progress and schedule a future review.
AI tutor
The optional AI tutor isn't enabled in this deployment. All lessons, exercises, quizzes, and search work fully without it.