идемпотентность api

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

Почему идемпотентность важна

В распределённых системах запросы могут теряться, дублироваться или выполняться дважды из-за retry-логики клиента. Представьте: клиент отправил запрос на списание 1000 рублей, не получил ответ (timeout), и автоматически повторил запрос. Если операция не идемпотентна, деньги спишутся дважды. Идемпотентная операция при повторном запросе с тем же идентификатором просто вернёт результат первого выполнения.

Идемпотентность в HTTP-методах

Спецификация HTTP определяет идемпотентность для различных методов:

• GET — идемпотентен и безопасен: только чтение, не меняет состояние
• HEAD — идемпотентен и безопасен: аналогично GET, без тела ответа
• PUT — идемпотентен: замена ресурса целиком, повторный запрос даёт тот же результат
• DELETE — идемпотентен: удаление несуществующего ресурса возвращает 404, но состояние не меняется
• POST — не идемпотентен по спецификации: создание нового ресурса при каждом вызове
• PATCH — может быть как идемпотентным, так и нет, в зависимости от семантики операции

Ключ идемпотентности (Idempotency-Key)

Для обеспечения идемпотентности не-идемпотентных операций (POST) используется паттерн Idempotency-Key: клиент генерирует уникальный UUID и передаёт его в заголовке запроса. Сервер сохраняет этот ключ вместе с результатом операции. При повторном запросе с тем же ключом сервер возвращает сохранённый результат, не выполняя операцию повторно.

Именно так работает Stripe API: при создании платежа клиент передаёт Idempotency-Key, и даже если запрос повторяется из-за сетевого сбоя, платёж создаётся ровно один раз.

Реализация идемпотентности на сервере

Типичная реализация:

1. Клиент генерирует UUID и отправляет в заголовке Idempotency-Key
2. Сервер проверяет, есть ли этот ключ в хранилище (Redis, БД)
3. Если ключ найден — возвращает сохранённый результат
4. Если не найден — выполняет операцию, сохраняет ключ и результат, возвращает результат

Хранить ключи нужно ограниченное время — обычно 24–48 часов. Важно гарантировать атомарность: проверка и сохранение ключа должны быть атомарными операциями, иначе возможны race conditions при параллельных запросах с одним ключом.

Идемпотентность и at-least-once delivery

В системах обмена сообщениями (Kafka, RabbitMQ, SQS) гарантия доставки «at least once» означает, что сообщение может быть доставлено более одного раза. Консьюмер должен обрабатывать дубликаты идемпотентно. Распространённое решение — хранить идентификаторы уже обработанных сообщений и пропускать дубликаты.

Идемпотентность в базах данных

SQL предоставляет встроенные механизмы идемпотентности: INSERT ... ON CONFLICT DO NOTHING (PostgreSQL), INSERT IGNORE (MySQL), MERGE (SQL Server, Oracle). В NoSQL-базах UPSERT-операции идемпотентны по своей природе.

При проектировании миграций баз данных все скрипты должны быть идемпотентными: повторный запуск не должен ломать уже применённые изменения. Для этого используют условные операторы: CREATE TABLE IF NOT EXISTS, ADD COLUMN IF NOT EXISTS.

Идемпотентность в инфраструктуре как код

Terraform, Ansible, Puppet и другие IaC-инструменты построены на принципе идемпотентности: декларативное описание желаемого состояния можно применять сколько угодно раз — система всегда приводит инфраструктуру к описанному состоянию. Это ключевое отличие от императивных скриптов, которые при повторном запуске могут сломать уже настроенную систему.

Тестирование идемпотентности

Идемпотентность нужно явно тестировать — она не возникает сама собой. В интеграционных тестах каждый мутирующий эндпоинт должен проверяться сценарием двойного вызова с одними параметрами: результат должен быть идентичен однократному вызову. Для Idempotency-Key паттерна тестируйте: первый вызов создаёт ресурс, второй возвращает тот же ID без создания нового, третий после истечения TTL ключа — создаёт новый. Chaos engineering инструменты (Chaos Monkey, Gremlin) помогают верифицировать идемпотентность в условиях сетевых сбоев и дублирования пакетов в production-подобном окружении.