Можно ли так спроектировать API?

Question

[Степан]

Делаю на Spring Boot простенький сервис чтения книг.
Накидал такую структуру API: api/users/{id}/shelves/{id}/books/{id}/pages
Получается такой порядок получения данных:

1. Сначала получаем список пользователей: api/users
   
2. Затем получаем список полок пользователя: api/users/{id}/shelves
   
3. Далее получаем список книг на полке: api/users/{id}/shelves/{id}/books
   
4. После чего получаем список страниц книги: api/users/{id}/shelves/{id}/books/{id}/pages
   
5. Дальше работаем со страницами книги.
   

Не будет ли ошибкой упростить структуру до:

1. Получаем список пользователей: api/users
   
2. Получаем список полок конкретного пользователя: api/users/{id}/shelves
   
3. Получаем список книг на конкретной полке: api/shelves/{id}/books
   
4. Получаем список страниц книги: api/books/{id}/pages
   
5. Дальше работаем со страницами книги.
   

Или такое упрощение не по фен-шую?

И ещё нюанс: с добавлением/просмотром/обновлением/удалением информации о книгах и полках особых сложностей нет.
Как быть, если книгу надо переместить с одной полки на другую?

Answer 1

[Rsa97]

Если id книги уникальный по всей базе, то достаточно api/books/{id}/pages.

Как быть, если книгу надо переместить с одной полки на другую?

Изменить запись в таблице связи shelves_books. Запрос PATCH /api/books/{id} с телом { "shelf": shelfId }.

Comments

[Степан]

Да, у всех объектов (пользователи, полки, книги, страницы) уникальные id + у страниц будут свои id внутри книги, чтобы можно было обращаться к конкретной странице. Например, "3", а не "27584", "4", а не "27615" (грубо).

Изменить запись в таблице связи shelves_books. Запрос PATCH /api/books/{id} с телом { "shelf": shelfId }.

А PUT, выходит, для другого? Принципиально ли его использование (а не PATCH)?

Как вариант, можно ведь книгу удалять с конкретной полки:
DELETE api/shelves/{id}/books/{id},
после чего:
POST api/shelves/{id}/books/{id}.
Это нормально?

[Rsa97]

Степан, PUT - обновление объекта целиком, PATH - обновление одного поля. В принципе, в данном контексте речь идёт о сущности "привязка книги к полке", а не "книга", то есть модель содержит только (bookId, shelfId), так что можно и PUT.
И да, я немного ошибся. Запрос должен быть PATH /api/shelves/{id}/book/{id} с телом { "shelf": shelfId }, поскольку одна и та же книга может стоять на полках у нескольких пользователей.
Можно через DELETE/POST, но возникнет проблема, если DELETE отработал, а POST, по каким-то причинам, не прошёл. Тогда книга будет потеряна.

[Степан]

Rsa97, в моем случае пользователь может манипулировать только своими книгами. По-хорошему, да, лучше, чтобы книга была на какой-то полке (чтобы не было книг "не на полке").
Я предполагаю, что книгами можно будет делиться: пользователь, посмотрев содержимое полки другого пользователя, может попросить взять книгу "почитать". В каком-то смысле "взятые почитать" это тоже "полка"... хотя лучше вынести их в отдельную сущность.

[Rsa97]

Степан, Тогда надо создавать экземпляры книг, ссылающиеся на содержимое книги. В этом случае каждый экземпляр будет иметь свой id и атрибуты, примерно так: (id, contentId, ownerId, shelfId, leaseUserId, leaseShelfId, leaseUntil).
В этом случае для перемещения книги достаточно PATH /api/books/{id} с телом { "shelf": shelfId }.
Для передачи книги "почитать": PATH /api/books/{id} с телом { "leaseUserId": userId, "leaseShelfId": shelfId, "leaseUntil": date }. Ну или без leaseShelfId, если для взятых почитать книг есть специальная полка, тогда её назначит бэкенд.
А уже сущность bookContent будет содержать название, автора, страницы и т.д.
Но доступ всё равно получается через GET /api/books/{id}/pages, так как связь между экземпляром и содержимым фиксированная и неизменная.

[Степан]

Rsa97, ещё такой вопрос возник. Будет ли нормальным выделить работу со своими объектами (книгами, полками, запросами) вот сюда:
/api/my/shelves
/api/my/books
/api/my/requests
То есть при обращении к этим ресурсам будет использоваться userId пользователя, от которого идёт запрос (его получим из токена в теле запроса).

"Общедоступные данные" будут доступны по привычным путям:
/api/users
/api/users/{id}/shelves
/api/books/{id}
При обращении к ним будут выдаваться данные, которые не связаны пользователем, от которого идёт запрос.

Или же лучше так не мудрить?