В чем разница между PUT и PATCH?

Разница между PUT и PATCH HTTP методами

Dля системного аналитика важно понимать семантику HTTP методов, так как они определяют контракт между клиентом и сервером при разработке REST API. PUT и PATCH — два метода для обновления ресурсов, но они работают совершенно по-разному.

PUT — Полное замещение ресурса

Определение: PUT отправляет полное представление ресурса и заменяет его целиком на сервере. Это идемпотентная операция — повторное выполнение дает тот же результат.

Семантика:

• Клиент отправляет полный объект со всеми полями
• Сервер полностью заменяет существующий ресурс
• Отсутствующие поля считаются "удалить" или "обнулить"
• Идемпотентно: PUT дважды = PUT один раз

Пример PUT запроса:

PUT /api/v1/users/123 HTTP/1.1
Content-Type: application/json

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "address": "123 Main St",
  "role": "admin"
}

Сервер заменяет всю запись пользователя 123 этими данными. Если раньше было еще какое-то поле — оно удалится.

PATCH — Частичное обновление ресурса

Определение: PATCH отправляет только измененные поля (дельта, различия) и обновляет только их. Это не идемпотентная операция в общем случае.

Семантика:

• Клиент отправляет только измененные поля
• Сервер merge-ит данные с существующим ресурсом
• Отсутствующие в запросе поля остаются неизменными
• Может быть неидемпотентным в зависимости от содержимого

Пример PATCH запроса:

PATCH /api/v1/users/123 HTTP/1.1
Content-Type: application/json

{
  "email": "newemail@example.com",
  "phone": "+9876543210"
}

Сервер обновляет только email и phone пользователя 123. Остальные поля (name, address, role) остаются как были.

Сравнительная таблица

Практические примеры

Сценарий 1: Обновление профиля пользователя

Текущие данные:

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com",
  "phone": "+111",
  "city": "Moscow",
  "subscription": "premium"
}

Пользователь хочет изменить только город:

С PUT:

PUT /api/v1/users/1
{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com",
  "phone": "+111",
  "city": "SPB",
  "subscription": "premium"
}

Применил: Нужно отправить все поля!

С PATCH:

PATCH /api/v1/users/1
{
  "city": "SPB"
}

Применил: Отправляешь только изменения ✅

Сценарий 2: Синхронизация двух систем

Есть микросервис, который синхронизирует данные в фоне. Если соединение разорвалось:

• PUT: Можно безопасно повторить синхронизацию, так как PUT идемпотентен
• PATCH: Опасно повторять, может привести к неправильному состоянию

Например, если PATCH добавляет к счету +100, повтор даст +200 (двойное добавление).

Проблемы и граничные случаи

Проблема 1: Версирование с PUT

Когда один клиент редактирует ресурс, а потом другой отправляет старую версию через PUT:

Клиент A читает версию v1: {name: "Alice", status: "active"}
Клиент B читает версию v1: {name: "Alice", status: "active"}
Клиент B обновляет: PUT {name: "Bob", status: "active"} → теперь {Bob, active}
Клиент A обновляет: PUT {name: "Alice", status: "inactive"} → теперь {Alice, inactive}

Утеряна версия {Bob, active} !

Решение: Добавить version/etag поле для проверки конфликтов.

Проблема 2: Undefined поля в PATCH

Что делать, если клиент отправляет {"field": null}?

• Удалить поле?
• Обнулить значение?
• Игнорировать?

Должны быть четкие правила в API документации.

JSON Patch стандарт (RFC 6902)

Для сложных случаев существует стандарт JSON Patch:

PATCH /api/v1/users/1
Content-Type: application/json-patch+json

[
  { "op": "replace", "path": "/email", "value": "new@example.com" },
  { "op": "add", "path": "/phone", "value": "+123" },
  { "op": "remove", "path": "/legacy_field" }
]

Это дает полный контроль над тем, какие операции выполняются.

Рекомендации для System Analyst

1. Выбирай PUT когда:

   • Клиент всегда отправляет полное состояние
   • Нужна идемпотентность (безопасные повторы)
   • Требования простые и стабильные
   • Нет конфликтов версионирования

2. Выбирай PATCH когда:

   • Объект имеет много полей, клиент изменяет только несколько
   • Нужно оптимизировать трафик
   • Часто обновляются частичные данные
   • Важна скорость (меньше данных = быстрее)

3. В спецификации API:

   • Явно определи, какой метод используется
   • Опиши поведение при отсутствующих полях
   • Приведи примеры для обоих случаев
   • Документируй версирование/конфликты

4. Безопасность:

   • Оба метода должны требовать аутентификацию
   • Проверяй права доступа (авторизация)
   • Логируй все изменения

Понимание разницы между PUT и PATCH критично для проектирования правильного API контракта и избежания ошибок при интеграции систем.