RESTful design
On this page 8 topics
Overview
Topics
- Resource modeling
- URLs
- status codes
- request/response contracts
Learn first
3 h of practice (estimate)
Learning outcomes
- Model resources, sub-resources, and collections from domain requirements.
- Design URLs, methods, and status codes for create, read, update, delete, and actions that are not CRUD.
- Define request/response contracts before writing code.
- Critique an API design against REST conventions.
Lessons
Lab and exercises
Lab
JNR-018-LAB1 · Shop API design doc
Outcomes: 1–4 · Time: ~3 h Design endpoints for products, categories, cart, and orders. Produce a table (method, URL, success status, error statuses) plus an example request and response for each endpoint, including checkout and cancel. Then ask a peer to review it against a checklist (nouns, plural names, status codes, no leaked database structure) and record the changes.
Acceptance: the design is reviewed before any implementation starts.
Exercises (assessment: design review using the DES rubric dimension)
| ID | Outcome | Task |
|---|---|---|
| JNR-018-EX01 | 1 | From "a library lends books to members; members can reserve books", list resources, collections, and sub-resources. |
| JNR-018-EX02 | 2 | Rewrite these as REST: POST /createUser, GET /getUser?id=3, POST /deleteUser. |
| JNR-018-EX03 | 2 | Give the status code for: created, updated with body, deleted, not found, duplicate, invalid body. |
| JNR-018-EX04 | 2 | Design the endpoint to cancel an order, including the response when it is already shipped. |
| JNR-018-EX05 | 3 | Write a contract (request, response, errors) for POST /products before any code. |
| JNR-018-EX06 | 4 | Critique: GET /products/delete/5, POST /products/5/get, creation returning 200, /api/tbl_products. List the problems. |
Show solutions
- EX01 Resources: book, member, reservation. Collections:
/books,/members,/reservations. Sub-resource:/members/{id}/reservations. - EX02
POST /users,GET /users/3,DELETE /users/3. - EX03 201, 200, 204, 404, 409, 400.
- EX04
POST /orders/{id}/cancelreturns200; if shipped,409with an error body explaining the state. - EX05 Request
{"name","priceCents","categoryId"};201withLocationand the created body;400for invalid fields;404or422for an unknown category (pick one and document it). - EX06 Verb in path,
GETthat deletes (unsafe), verb in path again, creation must be201, and the database table name leaks into the contract.
Outcome 4 is also exercised during the peer review in the lab.
Quiz
Outcomes: O1 resources · O2 URLs, methods, status codes · O3 contract-first · O4 critique.
A self-check for you: nothing is graded, saved or sent anywhere. Choose an answer, then check it. You can try again as often as you like.
Practical part
Six exercises JNR-018-EX01 to EX06 plus the design doc. Pass: at least five exercises and a design doc that was reviewed (DES rubric: meets or exceeds on contract clarity and consistency) before implementation.
Common mistakes
Verbs in paths; 200 for creation; exposing database IDs and structure as the contract.
Assessment
Design review using the DES rubric dimension.
Career relevance
API contracts (SRC-006) and API evolution (MID-062).