Чи варто використовувати PATCH або PUT в моєму API REST?

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

Є група. Кожна група має статус. Група може бути активована або інактивована адміністратором.

Чи повинен я визначити свою кінцеву точку як

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 можуть мати такі побічні ефекти. Якщо, наприклад, про видалення активації потрібно, скажімо, повідомляти користувачів поштою, DELETE не є правильним вибором; в цьому випадку ви , ймовірно , хочете створити деактивацію ресурс : 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-створення.

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 матиме). Зауважте, що можна використовувати й інші коди успіху.

також зверніться до thttp: //restcookbook.com/HTTP%20Methods/patch/

Caveat: 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/ deactivateпідресурс (пов’язаний 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, але з незначними змінами в точній реалізації.