REST API PATCH или PUT

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

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

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

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

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

этот шаблон полезен, когда "активация" группы имеет побочные эффекты, такие как платежи сделано, почта отправляется и так далее. Только пост и патч могут иметь такие побочные эффекты. Когда, например, удаление активации должно, скажем, уведомлять пользователей по почте, удаление не является правильным выбором; в этом случае вы, вероятно, захотите создать ресурс деактивации:POST /groups/{group_id}/deactivation.

это хорошая идея, чтобы следовать этим рекомендациям, потому что это стандартный договор делает это очень ясно для ваших клиентов, и все прокси и слои между клиентом и вами, когда безопасно повторить попытку, а когда нет. Допустим, клиент где-то с шелушащейся беспроводной доступ в интернет, и пользователь нажимает на кнопку "Отключить", который инициирует DELETE: если это не удается, клиент может просто повторить попытку, пока он не получит 404, 200 или что-нибудь еще, что он может обрабатывать. Но если он вызывает POST to deactivation он знает, что не следует повторять: сообщение подразумевает это.
У любого клиента теперь есть контракт, который, если следовать, защитит от отправки 42 писем "ваша группа была деактивирована", просто потому, что его HTTP-библиотека продолжала повторять вызов на серверную часть.

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

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 /groups/{group id}

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

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

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.

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

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

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

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

разница между запросами PUT и PATCH отражена в способ обработки сервером вложенного объекта для изменения ресурса
идентифицируется по запросу-URI. В запросе говоря, заключена сущность считается модифицированной версией ресурса, хранящегося на
исходный сервер, и клиент запрашивает, что сохраненная версия
быть заменен. с патчами, однако вложенный объект содержит набор инструкции, описывающие, как ресурс в настоящее время находится на
исходный сервер должен быть изменен для создания новой версии. заплата метод влияет на ресурс, определяемый запросом-URI, и это
также может иметь побочные эффекты на другие ресурсы, т. е. новые ресурсы
могут быть созданы или изменены существующие с помощью приложения a
ЗАПЛАТКА.

патч не является ни безопасным, ни идемпотентным как определено по [адресу rfc2616], Раздел 9.1.

клиенты должны выбрать, когда использовать патч, а не положить. Ибо
например, если размер документа исправления больше, чем размер
новые данные ресурса, которые будут использоваться в PUT, то это может сделать
смысл использовать пут вместо патча. А сравнение с постом еще больше трудно, потому что пост используется в самых разных формах и может
охватывать PUT и патч-подобные операции, если сервер выбирает. Если
операция не изменяет ресурс, указанный в запросе- Ури в предсказуемым образом, пост должен быть рассмотрен, а не патч
или поставить.

код ответа для патча

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

также смотрите более restcookbook.на COM/и HTTP%20Methods/патч/

предостережение: патч, реализующий API, должен исправляться атомарно. Это не должно быть возможно, что ресурсы наполовину исправлены по запросу GET.

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

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

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

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

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

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

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

или

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

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