REST — Nouns in the URL, Verbs in the Method
The bookshop's mobile app, its website and a partner's price-comparison tool all need to read books and place orders. An API is the set of requests your backend promises to understand. REST is the most common way to lay one out, and its whole trick is to reuse what HTTP already has.
The rule
The URL names the thing; the method says what to do to it.
REST organises an API around resources: the things your system knows about, like books, authors, reviews and orders. Each gets a URL, usually a plural noun:
| Request | Meaning | Success status |
|---|---|---|
GET /books |
list books | 200 OK |
GET /books/42 |
read book 42 | 200 OK |
POST /books |
create a book | 201 Created |
PUT /books/42 |
replace book 42 entirely | 200 OK |
PATCH /books/42 |
change some fields of book 42 | 200 OK |
DELETE /books/42 |
remove book 42 | 204 No Content |
Related resources nest: GET /books/42/reviews lists the reviews for book 42. Filtering, sorting and paging go in the query string: GET /books?author_id=7&sort=price&page=2.
A few properties of the methods are part of the contract:
- GET is safe: it must not change anything. Browsers, crawlers and caches assume they can repeat it freely.
- PUT and DELETE are idempotent: sending the same request twice leaves the same result as sending it once. Deleting book 42 twice still leaves it deleted.
- POST is neither: sending it twice usually creates two orders.
REST requests are also stateless: each carries its own credentials and all the context the server needs, so any server behind a load balancer can answer it.
The shortcut
To design any endpoint, find the noun, then pick the verb. If you catch yourself writing a verb into the path (/getBooks, /createOrder, /deleteReview), move it into the method.
Find the noun
The thing being changed is an order:
/orders/{id}, here/orders/310.
Some actions do not fit neatly; teams sometimes add a sub-resource like POST /orders/310/cancellation. That is fine, as long as the whole API picks one style and sticks to it.
Drills
Answer fast — trust the rule.
Which request fits REST for reading the reviews of book 42?
What is wrong with GET /deleteReview?id=9?
A client creates a new book with POST /books. Which status fits a success?
Which method is NOT idempotent, meaning repeating it can change the result again?
Where should "only books by author 7, cheapest first" go?
Remember
- The URL names the thing; the method says what to do to it.
- Find the noun, then pick the verb. Verbs in paths are a smell.
- GET is safe; PUT and DELETE are idempotent; POST is neither.