Что позволяет свойство идемпотентности у HTTP методов

Что проверяют

Понимаете ли вы практический смысл свойства: не определение, а то, что оно разрешает делать клиенту, шлюзу и интеграции. Аналитику следом обычно задают вопрос, как описать в требованиях повторную отправку платежа или заказа, раз POST идемпотентным не является.

Как отвечать

Идемпотентный метод это такой, у которого повтор одинакового запроса приводит сервер в то же состояние, что и один запрос. Речь именно о состоянии, а не об ответе: второй DELETE может вернуть 404, и идемпотентность от этого не нарушена.

По RFC 9110:

• безопасные (ничего не меняют): GET, HEAD, OPTIONS, TRACE, они же идемпотентны;
• идемпотентные, но не безопасные: PUT (полная замена ресурса) и DELETE;
• не идемпотентные по умолчанию: POST и PATCH. PATCH бывает идемпотентным, если тело описывает итоговое значение, и не бывает, если описывает действие вроде «прибавить единицу».

Что это даёт на практике:

• повторы при сбоях: если соединение оборвалось и ответ не пришёл, клиент, прокси или API-шлюз могут повторить запрос автоматически, не выясняя, дошёл ли первый;
• простые ретраи в интеграциях: очереди с доставкой «хотя бы один раз», таймауты, повторная отправка из мобильного приложения;
• проверяемость: тестировщик может прямо проверить, что повтор не плодит дубли.

Для неидемпотентных операций в спецификацию закладывают ключ идемпотентности. Клиент генерирует уникальный ключ в заголовке (у Stripe Idempotency-Key, у ЮKassa Idempotence-Key), сервер хранит его ограниченное время и на повтор возвращает сохранённый результат. В требованиях стоит прописать срок хранения ключа и реакцию на тот же ключ с другим телом.

Где спотыкаются

Путают идемпотентность с безопасностью и говорят, что PUT ничего не меняет.

Утверждают, что идемпотентный метод всегда возвращает одинаковый ответ. Код и тело могут отличаться, одинаковым должно быть состояние.

Считают свойство гарантией. RFC описывает, как метод должен себя вести, а соблюдает ли это сервер, зависит от разработчиков: GET, который что-то списывает, встречается и в живых системах.