Что такое идемпотентность в API
Идемпотентность — свойство операции давать одинаковый результат при одном или множественных выполнениях. В HTTP: GET/PUT/DELETE идемпотентны по RFC (повторный запрос не меняет state). POST не идемпотентен по умолчанию, но можно сделать таким через Idempotency-Key header (Stripe-паттерн). Критично для платежей, заказов, любых "create" endpoints где сетевой retry не должен создать дубликаты.
Ниже: подробности, пример, смежные термины, FAQ.
Подробности
- GET: идемпотентен (чтение не меняет state)
- PUT: идемпотентен (повторный PUT даёт тот же финальный state)
- DELETE: идемпотентен (удалить уже удалённое = 404 или 204, state не меняется)
- POST: обычно не идемпотентен (создаёт новую сущность каждый раз)
- Idempotency-Key header: клиент шлёт UUID; сервер кэширует response 24h; повторный запрос с тем же ключом возвращает сохранённый response
Пример
POST /v1/payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{"amount":100,"currency":"RUB"}Смежные термины
Больше по теме
Часто задаваемые вопросы
Зачем вообще Idempotency-Key?
Сетевой retry: сервер принял POST, обработал, но ответ потерялся в пути. Клиент думает "не прошло, повторю" → дубль. Idempotency-Key защищает от этого.
Как долго хранить ключи?
Stripe хранит 24 часа. Этого достаточно для retry-окна и не раздувает DB.
GET идемпотентен даже с rate limiting?
Да. Rate limit ≠ не-идемпотентность. Запрос либо разрешается и возвращает данные, либо отбивается с 429 — в обоих случаях state не меняется.