How to handle when REST resources are associated with existing resources and expand them?

Question

I am creating a REST API where I have Books and Users. They can exist only one unique Book. Although a user can have several books, different users can have the same book (or a link to it). The user can add additional information to the book (for example, rating).

My question is: what is the correct way to map resources when users "extend" an existing book resource with their own settings?

Example: the first user does not have books, but they can create a book. If the book does not exist, it is created, if it exists, they get access to it. Although they can add their own additional additional information.

Is it correct?

// All books with basic information required can be found in / books /: id Example: / books / 1 {

"id":1, "title":"The Empire", "description":"Description about the book", "serial":1234 

}

// If the user creates the book "Empire" (serial: 1234), they expand the existing book, but they added additional information, so this is actually a new URL, but it refers to the identifier of the book.

Example: / users / 421 / books / 1 /

 { "id":1, "title":"The Empire", "description":"Description about the book", "serial":1234, "rating":5.5, "note":"I liked the book but it was too long." } 

Or even:

 { "book":{ id":1, "title":"The Empire", "description":"Description about the book", "serial":1234, } "rating":5.5, "note":"I liked the book but it was too long." } 

Or even the url smth like / users / 421 / books / 1 / settings /

 { "rating":5.5, "note":"I liked the book but it was too long." } 

Answer 1

I would recommend allowing "reviews" to be associated with multiple parents (book, user), and then have a canonical resource for review as follows:

Book /books/{book-id}

 { "id":1, "title":"The Empire", "description":"Description about the book", "serial":1234 } 

Book reviews /books/{book-id}/reviews

 {[ { "id":1, "userId":user1, "bookId":1, "rating":5.5, "note":"I liked the book but it was too long.", "url":http://server/reviews/1 }, { "id":2, "userId":user2, "bookId":1, "rating":1, "note":"boo, i didn't like it!", "url":http://server/reviews/2 } ]} 

User reviews /users/{user-id}/reviews

 {[ { "id":1, "userId":user1, "bookId":1, "rating":5.5, "note":"I liked the book but it was too long.", "url":http://server/reviews/1 }, { "id":2, "userId":user2, "bookId":1, "rating":1, "note":"boo, i didn't like it!", "url":http://server/reviews/2 }, { "id":5, "userId":user1, "bookId":3, "rating":2, "note":"I like to read", "url":http://server/reviews/5 } ]} 

Canonical review resource /reviews/{review-id}

 {[ { "id":1, "userId":user1, "bookId":1, "rating":5.5, "note":"I liked the book but it was too long.", "url":http://server/reviews/1 }, { "id":5, "userId":user1, "bookId":3, "rating":2, "note":"I like to read", "url":http://server/reviews/5 } ]} 

Creating a new review can be a message to the user / reviews, books / reviews or resource reviews when implementing the server for these default POST services for the user ID or book ID.

The url link implementation has some options, such as atom: link.

Also, do not consider the raw identifier of books, users, and customer / consumer reviews of these services and instead expose the identifier as a URI.