Должен ли я использовать PATCH или PUT в моем REST API?

Я хочу спроектировать свою конечную точку отдыха с помощью подходящего метода для следующего сценария.

Есть группа. У каждой группы есть статус. Группа может быть активирована или деактивирована администратором.

Должен ли я спроектировать свою конечную точку как

PUT /groups/api/v1/groups/{group id}/status/activate

ИЛИ

PATCH /groups/api/v1/groups/{group id}

with request body like 
{action:activate|deactivate}

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

Дополнительная информация о частичной модификации ресурсов доступна в RFC 5789 . В частности, PUTметод описывается следующим образом:

Некоторым приложениям, расширяющим протокол передачи гипертекста (HTTP), требуется функция частичной модификации ресурсов. Существующий метод HTTP PUT позволяет только полную замену документа. Это предложение добавляет новый метод HTTP, PATCH, для изменения существующего ресурса HTTP.

R в REST обозначает ресурс

(Что неверно, потому что это означает «Репрезентативный», но это хороший трюк, чтобы помнить о важности ресурсов в REST).

О себе PUT /groups/api/v1/groups/{group id}/status/activate: вы не обновляете "активировать". «Активировать» - это не вещь, это глагол. Глаголы никогда не бывают хорошими ресурсами. Практическое правило: если действие, глагол, находится в URL-адресе, вероятно, это не RESTful .

Что ты делаешь вместо этого? Либо вы «добавляете», «удаляете» или «обновляете» активацию в группе, либо, если вы предпочитаете: манипулируете «статусом» -ресурса в группе. Лично я бы использовал «активации», потому что они менее двусмысленны, чем понятие «статус»: создание статуса неоднозначно, создание активации - нет.

• POST /groups/{group id}/activation Создает (или запрашивает создание) активацию.
• PATCH /groups/{group id}/activationОбновляет некоторые детали существующей активации. Поскольку в группе только одна активация, мы знаем, о каком ресурсе активации идет речь.
• PUT /groups/{group id}/activationВставляет или заменяет старую активацию. Поскольку в группе только одна активация, мы знаем, о каком ресурсе активации идет речь.
• DELETE /groups/{group id}/activation Отменит или удалит активацию.

Этот шаблон полезен, когда «активация» группы имеет побочные эффекты, такие как выполнение платежей, отправка писем и так далее. Только POST и PATCH могут иметь такие побочные эффекты. Когда, например, для удаления активации необходимо, например, уведомить пользователей по почте, УДАЛИТЬ - не правильный выбор; в этом случае вы , вероятно , хотите создать деактивацию ресурс : POST /groups/{group_id}/deactivation.

Это хорошая идея - следовать этим рекомендациям, потому что этот стандартный контракт очень ясно дает вашим клиентам, а все прокси и уровни между клиентом и вами знают, когда можно безопасно повторить попытку, а когда нет. Предположим, что клиент находится где-то с нестабильным Wi-Fi, и его пользователь нажимает «деактивировать», что вызывает DELETE: Если это не удается, клиент может просто повторить попытку, пока не получит 404, 200 или что-то еще, с чем он сможет справиться. Но если он запускает, POST to deactivationон знает, что повторять попытку нельзя: это подразумевает POST.
Теперь у любого клиента есть контракт, при соблюдении которого он будет защищать от отправки 42 электронных писем «ваша группа отключена» просто потому, что его HTTP-библиотека продолжала повторять вызовы на бэкэнд.

Обновление одного атрибута: используйте PATCH

PATCH /groups/{group id}

Если вы хотите обновить атрибут. Например, «статус» может быть атрибутом в группах, который можно установить. Такой атрибут, как «статус», часто является хорошим кандидатом для ограничения белого списка значений. В примерах используется некоторая неопределенная JSON-схема:

PATCH /groups/{group id} { "attributes": { "status": "active" } }
response: 200 OK

PATCH /groups/{group id} { "attributes": { "status": "deleted" } }
response: 406 Not Acceptable

При замене ресурса без побочных эффектов используйте PUT.

PUT /groups/{group id}

Если вы хотите заменить всю группу. Это не обязательно означает, что сервер фактически создает новую группу и выбрасывает старую, например, идентификаторы могут остаться прежними. Но для клиентов это может означать PUT : клиент должен предполагать, что он получает совершенно новый элемент, основываясь на ответе сервера.

В случае PUTзапроса клиент должен всегда отправлять весь ресурс, имея все данные, необходимые для создания нового элемента: обычно те же данные, что и для POST-create.

PUT /groups/{group id} { "attributes": { "status": "active" } }
response: 406 Not Acceptable

PUT /groups/{group id} { "attributes": { "name": .... etc. "status": "active" } }
response: 201 Created or 200 OK, depending on whether we made a new one.

Очень важным требованием является PUTидемпотентность: если вам требуются побочные эффекты при обновлении группы (или изменении активации), вы должны использовать PATCH. Поэтому, когда в результате обновления, например, отправляется электронное письмо, не используйте PUT.

Я бы рекомендовал использовать PATCH, потому что ваша группа ресурсов имеет много свойств, но в этом случае вы обновляете только поле активации (частичное изменение)

согласно RFC5789 ( https://tools.ietf.org/html/rfc5789 )

Существующий метод HTTP PUT позволяет только полную замену документа. Это предложение добавляет новый метод HTTP, PATCH, для изменения существующего ресурса HTTP.

Также, более подробно,

Разница между запросами PUT и PATCH отражается в том, как сервер обрабатывает закрытый объект для изменения ресурса,
идентифицированного Request-URI. В запросе PUT закрытый объект считается измененной версией ресурса, хранящегося на
исходном сервере, и клиент запрашивает
замену сохраненной версии . Однако с помощью PATCH закрытый объект содержит набор инструкций, описывающих, как ресурс, в настоящее время находящийся на нем, может быть создан или изменен уже существующим путем применения PATCH.
исходном сервере, должен быть изменен для создания новой версии. Метод PATCH влияет на ресурс, идентифицированный Request-URI, а
также МОЖЕТ иметь побочные эффекты для других ресурсов; т.е. новые ресурсы

PATCH не является ни безопасным, ни идемпотентным, как определено в [RFC2616], раздел 9.1.

Клиенты должны выбирать, когда использовать PATCH, а не PUT. Для
примера, если размер заплаты документа больше размера
новых данных о ресурсах , которые будут использованы в PUT, то это может сделать
смысл использовать PUT вместо пластыря. Сравнение с POST еще сложнее, потому что POST используется по-разному и может
включать в себя операции, подобные PUT и PATCH, если сервер того пожелает. Если
операция не изменяет ресурс, указанный в Request-URI, предсказуемым образом, следует рассматривать POST вместо PATCH
или PUT.

Код ответа для PATCH:

Код ответа 204 используется, потому что ответ не содержит тела сообщения (которое будет иметь ответ с кодом 200). Обратите внимание, что можно использовать и другие коды успеха.

также см. http://restcookbook.com/HTTP%20Methods/patch/

Предостережение: API, реализующий PATCH, должен обновлять атомарно. НЕ ДОЛЖНО быть возможным, чтобы ресурсы были исправлены наполовину по запросу GET.

Поскольку вы хотите разработать API с использованием архитектурного стиля REST, вам необходимо подумать о своих сценариях использования, чтобы решить, какие концепции достаточно важны для использования в качестве ресурсов. Если вы решите раскрыть статус группы в качестве подресурса, вы можете дать ей следующий URI и реализовать поддержку методов GET и PUT:

/groups/api/groups/{group id}/status

Обратной стороной этого подхода по сравнению с PATCH для модификации является то, что вы не сможете вносить изменения более чем в одно свойство группы атомарно и транзакционно. Если транзакционные изменения важны, используйте PATCH.

Если вы решите раскрыть статус как подресурс группы, это должна быть ссылка в представлении группы. Например, если агент получает группу 123 и принимает XML, тело ответа может содержать:

<group id="123">
  <status>Active</status>
  <link rel="/linkrels/groups/status" uri="/groups/api/groups/123/status"/>
  ...
</group>

Гиперссылка необходима для выполнения гипермедиа в качестве движка состояния приложения в архитектурном стиле REST.

Я бы предпочел что-то попроще, например activate/ deactivatesub-resource (связанный Linkзаголовком с rel=service).

POST /groups/api/v1/groups/{group id}/activate

или

POST /groups/api/v1/groups/{group id}/deactivate

Для потребителя этот интерфейс предельно прост и следует принципам REST, не отвлекая вас от концептуализации «активаций» как отдельных ресурсов.

Один из возможных вариантов реализации такого поведения:

PUT /groups/api/v1/groups/{group id}/status
{
    "Status":"Activated"
}

И, очевидно, если кому-то нужно его деактивировать, он PUTбудет иметь Deactivatedстатус в JSON.

В случае необходимости массовой активации / деактивации, PATCHможет перейти в игру (не для конкретной группы, а для groupsресурса:

PATCH /groups/api/v1/groups
{
    { “op”: “replace”, “path”: “/group1/status”, “value”: “Activated” },
    { “op”: “replace”, “path”: “/group7/status”, “value”: “Activated” },
    { “op”: “replace”, “path”: “/group9/status”, “value”: “Deactivated” }
}

В общем, это идея, как предлагает @Andrew Dobrowolski, но с небольшими изменениями в точной реализации.