Resource Modeling
Before writing a single endpoint, BookNook has to decide what its API is about. Is a loan its own thing, or a field on a book? Is a reservation a resource, or an action? These choices shape every URL, every response and every future change, and they are much cheaper to get right on paper than in production.
The rule
Model the nouns your callers care about, not the tables you store.
A resource is anything a caller wants to name, fetch or change. Resource modeling means choosing those nouns, their fields and how they relate.
Start from what callers do, then find the nouns in those sentences:
- "A member borrows a book" → nouns: member, book, and the borrowing itself, a loan.
- "A member reserves a book that is out" → a reservation.
- "A librarian sees overdue loans" → not a new noun; a filter on loans.
Resources come in two shapes:
- A collection holds many:
/v1/books. - An item is one member of it:
/v1/books/42.
Relationships can be shown by nesting (/v1/members/7/loans) or by reference, a field holding the other resource's id:
{
"id": 901,
"book_id": 42,
"member_id": 7,
"borrowed_on": "2026-09-25",
"due": "2026-10-09",
"returned_on": null
}Two habits keep models healthy:
- Turn important actions into resources. "Borrow" becomes creating a loan:
POST /v1/loans. The loan then has its own id, history and status, which a bareborrowaction would not. - Hide storage details. If the database splits a book across
books,editionsandshelf_locationstables, the API may still expose onebookresource. Callers should not break because you reorganised your tables.
The shortcut
Write three caller stories, underline the nouns, then ask of each: does a caller need to fetch or change this on its own? Yes → resource. No → a field or a filter.
Underline the nouns
member, book, loan, fine.
The trap is copying the database schema into URLs, like /v1/book_shelf_location_rows. That leaks internals and freezes them.
Drills
Answer fast — trust the rule.
Which is the best resource for "a member borrows a book"?
"Show me overdue loans." What should "overdue" become?
BookNook stores books in three tables. What should the API expose?
Which pair is a collection and one of its items?
Remember
- Model the nouns your callers care about, not the tables you store.
- Shortcut: underline the nouns; fetched or changed on its own → resource, otherwise a field or filter.
- Trap: leaking the database schema into the API.