Идемпотентный ли PATCH

Идемпотентность HTTP PATCH: Детальный разбор

Идемпотентность в контексте HTTP означает, что повторение одного и того же запроса (с одинаковыми данными) один или несколько раз подряд должно приводить к одному и тому же состоянию системы, что и первое выполнение. Вопрос о том, является ли PATCH идемпотентным, — один из самых обсуждаемых и неоднозначных в REST API, поскольку ответ зависит от конкретной реализации и семантики используемого формата запроса.

Краткий ответ: НЕТ, по умолчанию PATCH не является строго идемпотентным

Согласно RFC 5789, который определяет метод PATCH, идемпотентность метода не гарантирована стандартом. В отличие от методов GET, PUT, DELETE и даже OPTIONS и HEAD, которые по спецификации RFC 7231 являются идемпотентными, PATCH может быть как идемпотентным, так и неидемпотентным — это зависит от формата изменений (patch document), который клиент отправляет на сервер.

Почему PATCH часто неидемпотентен?

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

Пример неидемпотентного PATCH (на JSON Patch):

Допустим, у нас есть счетчик просмотров статьи. Первый запрос увеличивает его.

PATCH /articles/123 HTTP/1.1
Content-Type: application/json-patch+json

[
    { "op": "add", "path": "/views", "value": 1 }
]

Повторение этого точно такого же запроса приведет к увеличению счетчика до 2, затем до 3 и так далее. Состояние ресурса после каждого запроса разное — нарушена идемпотентность.

// Состояние ДО первого запроса: {"views": 0}
// После 1-го запроса: {"views": 1}
// После 2-го (идентичного) запроса: {"views": 2}  // Состояние изменилось!

Как сделать PATCH идемпотентным?

Идемпотентность PATCH достигается, если использовать форматы инструкций, которые описывают желаемое конечное состояние части ресурса, а не относительное изменение. Сервер должен интерпретировать запрос как "установить значение X в поле Y", а не "добавить N к полю Y".

Пример идемпотентного PATCH (на JSON Merge Patch или явное задание значения):

PATCH /articles/123 HTTP/1.1
Content-Type: application/merge-patch+json

{
    "views": 5
}

Повторение этого запроса любое количество раз всегда будет устанавливать количество просмотров в 5. Состояние ресурса после первого и последующих идентичных запросов одинаково — идемпотентность соблюдена.

Другой пример — использование идемпотентных операций в JSON Patch:

PATCH /articles/123 HTTP/1.1
Content-Type: application/json-patch+json

[
    { "op": "replace", "path": "/title", "value": "Новый заголовок" }
]

Операция replace идемпотентна: сколько бы раз вы ни заменяли заголовок на "Новый заголовок", результат будет один и тот же.

Рекомендации для QA Engineer и разработчика

• Тестирование: При тестировании API, использующего PATCH, нельзя автоматически предполагать его идемпотентность. Необходимо:

    *   Изучить документацию API. Ответственные разработчики должны явно указывать, является ли их реализация PATCH идемпотентной.
    *   Эмпирически проверять поведение: отправлять идентичный PATCH-запрос дважды подряд и сравнивать конечное состояние системы и коды ответа.
    *   Проверять сценарии повторной отправки запросов из-за таймаутов или сетевых сбоев — типичный кейс, где важна идемпотентность.

• Проектирование API (совет для разработчиков):

    *   Старайтесь проектировать **PATCH как идемпотентный**. Это значительно повышает надежность API, особенно в нестабильных сетевых условиях.
    *   Используйте форматы, подобные **JSON Merge Patch**, или ограничьтесь идемпотентными операциями (`replace`, `set`).
    *   Если идемпотентность невозможна (например, для операций типа "инкремент"), рассмотрите альтернативы: использование **POST** для отдельного неидемпотентного действия или реализацию механизма **идемпотентных ключей (Idempotency-Key)** на стороне сервера для безопасного повтора операций.

Вывод

Метод PATCH по своей природе не гарантирует идемпотентность. Он — "подозреваемый", чье поведение полностью определяется содержимым запроса и логикой его обработки на сервере. Для инженера QA критически важно понимать это различие и не полагаться на стандартные ожидания от идемпотентных методов (PUT, DELETE), тестируя PATCH-эндпоинты. Лучшей практикой является явная договоренность в команде и документации о семантике используемых PATCH-запросов.