Какой тип запроса в REST использовать для изменения?

Выбор типа REST-запроса для изменения ресурса

Для изменения данных в RESTful API используется PATCH или PUT. Выбор между ними зависит от характера изменений: частичное обновление или полная замена ресурса.

PUT: Полная замена ресурса

Метод PUT предполагает, что клиент отправляет полное представление ресурса, заменяя существующее. Сервер обрабатывает запрос как замену всего ресурса по указанному URI.

Характеристики PUT:

• Идемпотентность: Многократный вызов с одинаковыми данными даёт тот же результат.
• Требует всех полей: Даже если изменяется одно поле, нужно отправить полный ресурс.
• Использование: Подходит, когда клиент управляет всем состоянием ресурса.

// Пример PUT-запроса для обновления пользователя с ID=1
PUT /api/users/1
Content-Type: application/json

{
  "id": 1,
  "name": "Иван Петров",
  "email": "ivan@example.com",
  "age":   30
}

В этом примере все поля пользователя передаются заново. Если поле age опустить, оно может быть сброшено в null (зависит от реализации).

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

Метод PATCH предназначен для частичных изменений. Клиент отправляет только те поля, которые нужно изменить.

Характеристики PATCH:

• Не идемпотентен по умолчанию: Повторный вызов может дать разный результат (например, инкремент значения).
• Экономия трафика: Передаются только изменяемые данные.
• Гибкость: Поддерживает сложные операции (например, добавление в массив).

// Пример PATCH-Merge для обновления только имени и возраста
PATCH /api/users/1
Content-Type: application/json

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

Только поля name и age будут обновлены, остальные останутся без изменений.

Ключевые различия в таблице

Форматы PATCH-запросов

Стандарт PATCH допускает разные форматы описания изменений:

JSON Patch (RFC 6902)

Специфический формат для описания операций над JSON

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

[
  { "op": "replace", "path": "/name", "value": "Иван Петров" },
  { "op": "add", "path": "/phone", "value": "+79161234567" }
]

JSON Merge Patch (RFC 7386)

Более простой подход, похожий на обычный JSON

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

{
  "name": "Иван Петров",
  "phone": "+79161234567"
}

Рекомендации по выбору

1. Используйте PATCH, когда:

   • Нужно изменить только несколько полей большого ресурса
   • Хотите минимизировать трафик данных
   • Изменения сложные (добавление в массивы, инкременты)

2. Используйте PUT, когда:

   • Клиент имеет полное представление ресурса
   • Требуется гарантированная идемпотентность
   • Ресурс относительно небольшой

Важные аспекты при тестировании

При тестировании API, обрабатывающего изменения, QA Engineer должен проверять:

• Валидацию данных: Обработка некорректных или частичных данных в PUT
• Идемпотентность: Повторные PUT-запросы не должны менять результат
• Частичные обновления: PATCH должен корректно обновлять указанные поля
• Ошибки: Ответы 400/422 при неверных данных, 404 при отсутствии ресурса
• Конфликты: Обработка одновременных изменений (оптимистичная блокировка)
• Безопасность: Проверка прав доступа (только авторизованные пользователи)

Заключение

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