RavnaryA Knowledge Platform
Colour theme

Card 04/ 11

Take the quiz

ExampleDifficulty: Intermediate1 min

Resource Example: A Bookshop's Books, Authors and Reviews

Three related resources, and the paths that reach them without repeating any.

Deriving paths from a domain means turning its nouns into collections, its relationships into sub-collections or links, and giving each resource one canonical path. A bookshop sells books, each written by one or more authors, and readers write reviews of books. The trace takes it from nouns to paths, one decision per frame.

A bookshop's nouns turned into paths, one design decision at a time

InputBooks, authors and reviews; a review belongs to one book

  1. The nouns

    1. booknoun
    2. author
    3. review

    Each thing a client needs to name is a candidate resource.

  2. Each noun becomes a collection

    1. /books
    2. /authors
    3. /books/{id}/reviewsnested

    A review exists only for one book, so its collection sits under the book.

  3. Each collection gains an item path

    1. /books/{id}
    2. /authors/{id}
    3. /reviews/{id}canonical

    A review has its own id, so one review is reached at the top level.

  4. The many-to-many link becomes a sub-collection

    1. /authors/{id}/bookslink
    2. authorIds in each book
    3. /books/{id}/reviews

    Listing an author's books is a filtered view of /books, not a second copy.

ResultSix paths cover the domain, and each book, author and review has exactly one canonical URL.

The final set, with the methods each path takes:

text
GET, POST           /books
GET, PATCH, DELETE  /books/{id}
GET, POST           /books/{id}/reviews
GET, PATCH, DELETE  /reviews/{id}
GET, POST           /authors
GET, PATCH          /authors/{id}
GET                 /authors/{id}/books

Why reviews are created under the book. POST /books/12/reviews says which book the review is for in the path, so the body does not need to.

Why one review is read at the top level. /reviews/3 stays valid even if the review moves between books, and a client holding only the review id does not need the book id.

Why /authors/{id}/books is read-only. It is a view onto /books filtered by author. Creating a book there would give books two places to be created.

← → move through sections and cards