CRUD Operations
Almost every resource in BookNook needs the same four abilities: add one, look at it, change it, remove it. That is CRUD: create, read, update, delete. Once you map these four onto HTTP the same way everywhere, a developer who has used /books can use /members and /fines without reading anything new.
The rule
Create is POST to the collection; the rest act on the item.
The standard mapping, with the responses a caller should expect:
| Operation | Request | Success response |
|---|---|---|
| Create | POST /v1/books with the new book |
201 Created, Location: /v1/books/43, the new book |
| Read many | GET /v1/books |
200 OK with a list |
| Read one | GET /v1/books/43 |
200 OK with the book, or 404 |
| Update part | PATCH /v1/books/43 with changed fields |
200 OK with the updated book |
| Replace | PUT /v1/books/43 with the full book |
200 OK (or 204) |
| Delete | DELETE /v1/books/43 |
204 No Content |
A create request and its answer:
POST /v1/books HTTP/1.1
Content-Type: application/json
{"title": "Dune", "isbn": "9780441013593", "shelf": "C2"}
HTTP/1.1 201 Created
Location: /v1/books/43
Content-Type: application/json
{"id": 43, "title": "Dune", "isbn": "9780441013593", "shelf": "C2", "available": true}Notice the server chose the id and filled in available. Returning the full resource saves the caller a second GET.
Details that separate a careful API from a sloppy one:
- Validate on create and update: missing required fields →
422with a message saying which field. - Read-only fields such as
idandcreated_atare set by the server; ignore or reject attempts to change them. - Deleting what is not there: many APIs answer
404; others answer204because the end state, "gone", is already true. Pick one and document it. - Soft delete: a library may never truly erase a loan, for records.
DELETEcan mark it removed, as long as it then behaves as gone to callers.
The shortcut
Decide two things for any operation: collection or item? which verb? Only create targets the collection; everything else names the item.
Add it to the catalogue
New item, id unknown yet → collection:
POST /v1/books. Response201.
Drills
Answer fast — trust the rule.
Which request creates a new member?
What is the usual success response to DELETE /v1/books/43?
A create request omits the required title. What should BookNook reply?
A caller sends PATCH /v1/books/43 with {"id": 99}. What is the best behaviour?
Remember
- Create is POST to the collection; the rest act on the item.
- Shortcut: collection or item, then which verb.
- Trap: missing
201andLocationon create, and letting callers change read-only fields.