REST — Nouns in the URL, Verbs in the Method
Before writing a line of ReadingRoom's API, decide its URLs. Get them wrong and you end up with /getAllBooks, /deleteBookById and /doLoan — every endpoint a special case. REST gives you a small set of patterns that clients can predict.
The rule
URLs name things; methods say what to do; status codes say what happened.
In REST, everything the API exposes is a resource with an address. A collection is a plural noun, and one item is that noun plus its id:
| Method + URL | Meaning | Success status |
|---|---|---|
GET /books |
list books | 200 OK |
GET /books/7 |
read book 7 | 200 OK (404 if missing) |
POST /books |
create a book | 201 Created + Location |
PUT /books/7 |
replace book 7 | 200 OK or 204 No Content |
DELETE /books/7 |
remove book 7 | 204 No Content |
Related resources nest: GET /members/5/loans lists member 5's loans. Filters go in the query string: GET /books?author=Herbert.
Two more REST ideas matter from day one. Requests are stateless: each one carries everything the server needs, so any server instance can answer it. And GET, PUT and DELETE are idempotent: sending the same one twice leaves the data as sending it once would. POST is not — two POSTs make two books.
The shortcut
When an endpoint idea arrives as a sentence, pull out the noun for the URL and the verb for the method. "Delete the book with id 7" → DELETE /books/7. If you catch a verb inside your URL, move it into the method.
Say it in words
"Borrow book 3 for member 5."
The trap: POST /loans/create. The word "create" repeats what POST already says.
Drills
Answer fast — trust the rule.
Which endpoint best follows REST for "update book 7's title"?
Which of these methods is NOT idempotent?
Where does a filter such as "only books by Herbert" belong?
A successful POST /books should usually answer with what?
Remember
- URLs name things; methods say what to do; status codes say what happened.
- Pull the noun into the URL, the verb into the method.
- POST is not idempotent; GET, PUT and DELETE are.