В чем разница между методами PUT и PATCH с точки зрения семантики REST и их практической реализации?

Question

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

YeaHub · Accepted Answer

Семантические различияPUT - Полное обновлениеПолная замена существующего ресурсаКлиент должен передать все поля ресурсаОтсутствующие поля сбрасываются в значения по умолчанию или nullИдемпотентный методPATCH - Частичное обновлениеИзменение только указанных полей ресурсаКлиент передает только изменяемые поляНепереданные поля сохраняют свои значенияМожет не быть идемпотентнымПрактическая реализацияПример PUT запросаjson// Исходный ресурс
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user",
  "createdAt": "2023-01-01"
}

// PUT запрос /api/users/123
{
  "name": "Johnathan Doe",
  "email": "johnathan@example.com"
}

// Результат (роль и createdAt потеряны!)
{
  "id": 123,
  "name": "Johnathan Doe",
  "email": "johnathan@example.com"
}Пример PATCH запросаjson// Исходный ресурс
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user",
  "createdAt": "2023-01-01"
}

// PATCH запрос /api/users/123
{
  "name": "Johnathan Doe"
}

// Результат (остальные поля сохранены)
{
  "id": 123,
  "name": "Johnathan Doe",
  "email": "john@example.com",
  "role": "user",
  "createdAt": "2023-01-01"
}Форматы PATCH запросовJSON Merge Patchjson{
  "name": "New Name",
  "address": {
    "city": "New City"
  }
}JSON Patch (RFC 6902)json[
  { "op": "replace", "path": "/name", "value": "New Name" },
  { "op": "add", "path": "/address/city", "value": "New City" },
  { "op": "remove", "path": "/unusedField" }
]Критерии выбора методаИспользуйте PUT когда:Обновляете весь ресурсКлиент имеет полное представление ресурсаТребуется гарантия идемпотентностиПростые структуры данныхИспользуйте PATCH когда:Обновляете часть ресурсаКлиент не имеет полных данныхБольшие объекты с множеством полейОптимизация трафика важнаВывод: PUT подходит для простых сценариев полного обновления, тогда как PATCH более гибок для сложных ресурсов и оптимизации сетевого трафика. Выбор зависит от конкретных требований приложения и степени контроля клиента над ресурсом.