Хороший дизайн REST API для операций над наборами ресурсов - PullRequest
Новая
       15

Хороший дизайн REST API для операций над наборами ресурсов

0 голосов
/ 13 февраля 2020

С REST довольно ясно, как работать с ресурсами, например, 

PUT /users/{userId} - updates the user with userId
GET /users/{userId} - reads the user with userId

Аналогично для наборов ресурсов 

POST /users - creates a new user
GET /users/{userId}/books - reads list of books from a user
GET /users/{userId}/books?filter=x - reads list of books from a user with specific filter

Что если я хочу разработать более сложные операции на наборы ресурсов , например

  1. с телом запроса, добавление списка книг в существующий список и прием дубликатов (в основном, конкатенация списка) 
POST /users/{userId}/books 
or PUT /users/{userId}/books 
or PATCH?
or POST /users/{userId}/books/concatenate
с телом запроса, добавить список книг в существующий список, но без дубликатов (в основном, слияние списка) 
POST /users/{userId}/books 
or PUT /users/{userId}/books 
or PATCH?
or POST /users/{userId}/books/merge
также для удаления частей наборов ресурсов: с телом запроса удалите список книг из существующего списка с определенным свойством 
POST /users/{userId}/books/delete?category=x 
or DELETE /users/{userId}/books?category=x
или удаление всех ресурсов в наборе ресурсов: 
POST /users/{userId}/books/delete_all 
or DELETE /users/{userId}/books

Буду благодарен за некоторые советы или рекомендации

1 Ответ

1 голос
/ 19 февраля 2020

«Ресурсные наборы», с точки зрения REST, являются фикцией. Есть только ресурсы. Что касается HTTP-компонента общего назначения, то для следующего URI не существует никакой связи, подразумеваемой _1001 * 

/users
/users/{userId}
/users/{userId}/books
/users/{userId}/books?filter=x
/users/{userId}/books/concatenate

. Они полностью независимы друг от друга; например, DELETE /users не подразумевает ничего о других ресурсах.

Мы люди склонны назначать идентификаторы в шаблонах, которые имеют смысл, но машины не не волнует.

с телом запроса, добавить список книг в существующий список и принимать дубликаты (в основном, конкатенация списка)

PUT и PATCH имеют удаленный авторская семантика; они действуют так, как вы ожидаете, если вы пытаетесь редактировать копию файла на сервере. Вы GET копируете текущее представление ресурса, вносите изменения в локальную копию и затем запрашиваете, чтобы сервер изменил свою копию, чтобы она соответствовала вашей копии. С PUT вы отправляете полную копию своего представления ресурса; с помощью PATCH вы отправляете патч-документ, в котором описаны сделанные вами изменения.

Можно использовать POST ; HTML прекрасно ладил, используя только GET и POST, и сеть захватила весь мир.

Вам не нужен отдельный ресурс для POST; Вы можете использовать один, если хотите, но это не обязательно.

с телом запроса, добавить список книг в существующий список, но без дубликатов (в основном, слияние списка)

Ничего особенного; в HTTP мы согласовываем семантику сообщений запроса и ответа. То, что сервер выбирает, является проблемой реализации. См. Fielding 2002 .

Так что, если я отправлю вам представление списка с дублирующимися записями, и вы удалите дубликаты, это "хорошо"; вам просто нужно проявить некоторую осторожность с вашими ответами, чтобы убедиться, что вы не подразумеваете, что вы приняли запрошенное представление как есть.

С PATCH это немного нечетко, поскольку RF C описывает все или ничего семантика, но на основе используемого языка разумно сделать вывод, что реализация также ограничена.

также для удаления частей наборов ресурсов: с телом запроса удалите список книг из существующего списка с определенным свойством

Give RF C 7231 внимательно прочитайте: УДАЛИТЬ не совсем означает, на что намекают ваши примеры. DELETE разрушает связь между ключом (целевой uri) и значением (представления ресурса), но это не обязательно означает «а также сбор мусора представление».

Эта же идея выражена другим образом - предположим, что я GET /list-of-books с сервера, а возвращаемое представление представляет собой список из трех книг. В случае, когда я хочу, чтобы этот ресурс вместо этого возвращал представление пустого списка, DELETE - неправильный инструмент. DELETE сообщает серверу, что я хочу, чтобы будущие вызовы GET /list-of-books возвращали 404 Not Found или, возможно, 410 Gone. Если я действительно хочу 200 OK с пустым списком, тогда мне нужно PUT / PATCH / POST / et c. ресурс.

удаление всех ресурсов в наборе ресурсов

Та же проблема, что и раньше.

С REST довольно ясно, как работа с ресурсами

Это проблема - НЕ понятно, как работать с ресурсами. Сеть изобилует литературой, из которой всего 10 * * (мы используем REST для извлечения документов, которые извлекают уроки из REST - невероятная ирония).

REST включает унифицированный интерфейс в качестве ограничения. В HTTP этот интерфейс фактически является хранилищем документов. PUT и PATCH просто редактируют содержимое документа - что вполне удовлетворительно, если ваш домен anemi c или декларативный. Для всего остального, где у нас нет стандартизированной семантики, мы используем POST.

См. Джим Уэббер, 2011: «Вы должны научиться использовать HTTP для запуска деловой активности как побочного эффекта перемещения документов по сети».

...