Для чего нужен HTTP метод PATCH?

HTTP метод PATCH: назначение и отличие от PUT

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

Основное отличие: PUT vs PATCH

PUT — полная замена ресурса

При отправке PUT-запроса сервер полностью заменяет указанный ресурс переданными данными. Если не передать какое-то поле, оно удалится или переустановится в значение по умолчанию.

Первоначальное состояние пользователя:
{
  "id": 123,
  "name": "Иван",
  "email": "ivan@example.com",
  "phone": "+7-900-123-4567",
  "country": "РФ"
}

ПРИ PUT запросе:
PUT /users/123
{"name": "Иван Петров"}

Результат (полная замена):
{
  "id": 123,
  "name": "Иван Петров",
  "email": null,
  "phone": null,
  "country": null
}

Все поля, которые не передали, теряются!

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

При отправке PATCH-запроса сервер обновляет только переданные поля, остальные остаются неизменными.

Первоначальное состояние пользователя (то же):
{
  "id": 123,
  "name": "Иван",
  "email": "ivan@example.com",
  "phone": "+7-900-123-4567",
  "country": "РФ"
}

ПРИ PATCH запросе:
PATCH /users/123
{"name": "Иван Петров"}

Результат (обновлены только переданные поля):
{
  "id": 123,
  "name": "Иван Петров",
  "email": "ivan@example.com",
  "phone": "+7-900-123-4567",
  "country": "РФ"
}

Это то, что нам нужно!

Когда использовать PATCH

1. Обновление отдельных полей

Если пользователь хочет изменить только имя, отправляем только имя:

PATCH /users/123
Content-Type: application/json

{"name": "Иван Петров"}

Вместо того чтобы отправлять весь объект с PUT.

2. Мобильные приложения с медленным интернетом

Передача только одного поля вместо всего объекта экономит трафик:

Мобильное приложение меняет только статус заказа:
PATCH /orders/456
{"status": "shipped"}

Вместо PUT с полным заказом (100 полей):
PUT /orders/456
{весь заказ полностью}

3. Операции с ограничениями доступа

Пользователь может менять только своё имя и фото, но не может менять роль и дату регистрации:

ПЕН /users/me
{"name": "Новое имя", "photo": "url"}

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

4. Синхронизация данных при конфликтах

Если на сервере уже есть версия 2 ресурса, а клиент отправляет обновление для версии 1:

Сервер может запустить трёхсторонний merge:
- Версия 1 (клиент)
- Версия 2 (сервер)
- PATCH с изменениями

Итог: в результате будут изменены только нужные поля,
остальное из версии 2 сохранится.

JSON Patch — стандартный формат PATCH

Для сложных обновлений используется стандарт JSON Patch (RFC 6902):

PATCH /users/123
Content-Type: application/json-patch+json

[
  {"op": "replace", "path": "/name", "value": "Иван Петров"},
  {"op": "add", "path": "/tags", "value": ["vip", "premium"]},
  {"op": "remove", "path": "/newsletter"}
]

Этот формат позволяет выразить сложные операции (добавление, удаление, перемещение), но сложнее в реализации.

Когда НЕ использовать PATCH

1. Создание новых ресурсов

Для создания используй POST, не PATCH.

2. Если нет разницы между PUT и PATCH

Некоторые API работают одинаково и для PUT, и для PATCH. Это не ошибка, но неоптимально.

3. Когда нужна атомарность

Если обновление зависит от старых значений (например, +1 к счётчику), PATCH может привести к race conditions. Используй транзакции на сервере.

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

• Обсуди с разработчиками, поддерживает ли ваш API PATCH для частичных обновлений
• Документируй, какие поля допускают PATCH, а какие требуют полной замены (PUT)
• Валидируй, что PATCH не создаёт конфликты данных (например, если меняется зависимое поле)
• Тестируй边случаи: отправка пустого PATCH, PATCH с null, PATCH с игнорируемыми полями

ПАТЧ — это экономия трафика, удобство для клиента и безопасность данных. Правильное применение PATCH делает API более гибким и надёжным.