Метод HTTP PATCH: Частичные Обновления в REST API. Начало
HTTP PATCH применяет частичные изменения к ресурсу. Он решает распространённую задачу проектирования API: обновление определённых полей без замены всего ресурса. Рассмотрим метод PATCH, чем он отличается от PUT и POST, и как эффективно реализовать запросы PATCH.
Пример: Обновление роли пользователя
PATCH /api/users/12345 HTTP/1.1
Content-Type: application/json
{
"role": "Senior Developer"
}
Сервер обновляет только поле роли, оставляя остальные поля неизменными.
PATCH, PUT или POST
PATCH
Цель: частичное обновление;
Отправляемые данные: только изменяемые поля;
Идемпотентность: не является идемпотентным, но часто запросы PATCH разрабатываются с учётом возможности их идемпотентности;
Использование: обновление отдельных полей ресурса;
Результат: обновляются только отправленные поля.
PUT
Цель: полная замена;
Отправляемые данные: ресурс целиком;
Идемпотентность: да;
Использование: замена всего ресурса;
Результат: заменяется ресурс целиком.
POST
Цель: замена или действие;
Отправляемые данные: новый ресурс;
Идемпотентность: нет;
Использование: создание нового ресурса или действие над ресурсом;
Результат: отправленные поля заменяются, не отправленные устанавливаются в значения по умолчанию.
Когда не использовать
1. Нужно заменить весь ресурс (используйте PUT).
2. Обновления неидемпотентны (рассмотрите POST).
3. Контракт API требует полной проверки всех полей при каждом обновлении.
4. Ресурса не существует (верните 404 и используйте POST для его создания).
Форматы запросов
1. JSON Merge-patch
Отправляет JSON-объект, содержащий только поля для обновления:
PATCH /api/users/12345
Content-Type: application/merge-patch+json
{
"email": "updated@example.com",
"role": "Manager"
}
Этот подход прост и интуитивно понятен, но может быть неоднозначным для вложенных объектов и значений NULL.
2. JSON Patch
JSON Patch (RFC 6902) обеспечивает точный контроль с помощью массива операций:
PATCH /api/users/12345
Content-Type: application/json-patch+json
[
{ "op": "replace", "path": "/email", "value": "new@example.com" },
{ "op": "add", "path": "/phone", "value": "+1-555-0123" },
{ "op": "remove", "path": "/temporary_field" }
]
Доступные операции:
- add – добавление нового поля или элемента массива;
- remove – удаление поля;
- replace – обновление существующего поля;
- move – перемещение значения в новое место;
- copy – копирование значения в новое место;
- test – проверка значения перед применением операции.
Стандартные ответы метода PATCH
Успешные ответы:
- 200 OK — обновление успешно, возвращается обновлённый ресурс;
- 204 No Content - обновление успешно, но тело ответа отсутствует;
- 202 Accepted - обновление принято для асинхронной обработки.
Ответы с ошибкой:
- 400 Bad Request - неверный формат или данные;
- 401 Unauthorized - требуется аутентификация;
- 403 Forbidden - недостаточные права доступа;
- 404 Not Found - ресурса не существует;
- 409 Conflict - обновление конфликтует с текущим состоянием ресурса;
- 422 Unprocessable Entity - валидный JSON, но семантически некорректный.
Понимание идемпотентности PATCH
Идемпотентность означает, что многократное применение одного и того же запроса дает тот же результат, что и однократное применение. Это свойство имеет решающее значение для безопасной обработки повторных попыток в сети. PATCH по своей природе не является идемпотентным, но многие API разрабатывают запросы PATCH таким образом, чтобы они вели себя идемпотентно для обеспечения надёжности и безопасных повторных попыток.
Пример идемпотентного PATCH:
PATCH /api/users/12345
{
"email": "consistent@example.com"
}
Многократная отправка этого запроса приводит к одному и тому же итоговому состоянию ресурса.
Пример неидемпотентного PATCH:
PATCH /api/products/789
{
"inventory_adjustment": -5
}
Каждый запрос вычитает 5 единиц инвентаря, приводя к различным итоговым состояниям ресурса.
Окончание следует…
Источник: https://blog.postman.com/http-patch-method/