Что такое идемпотентность в API

• 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"}

• Rate Limiting
• Webhook
• JWT

Идемпотентность в API — это свойство операции, при котором многократное выполнение одной и той же команды приводит к одному и тому же результату. Например, HTTP-метод PUT является идемпотентным, так как повторный запрос на обновление ресурса не изменит его состояние, если данные остаются неизменными.

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

Например, в системе электронной коммерции клиент может повторно отправить запрос на отмену заказа. Если этот запрос идемпотентен, то повторное выполнение не приведет к ошибкам или нежелательным последствиям, таким как множественное аннулирование одного и того же заказа.

Кроме того, идемпотентные операции облегчают обработку ошибок и управление транзакциями. Разработчики могут быть уверены, что повторные запросы не вызовут дополнительных затрат на ресурсы или изменения в состоянии системы.

Рассмотрим пример использования идемпотентного метода PUT для обновления информации о пользователе в RESTful API. Предположим, у нас есть API для управления пользователями, и мы хотим обновить информацию о пользователе с идентификатором 123.

PUT /api/users/123
{
  "name": "Иван",
  "email": "ivan@example.com"
}

Если мы отправим этот запрос один раз, сервер обновит информацию о пользователе. Если мы повторим тот же запрос, результат будет тем же: информация о пользователе останется неизменной, если данные не изменились.

Однако, если мы попытаемся выполнить запрос с новыми данными:

PUT /api/users/123
{
  "name": "Петр",
  "email": "petr@example.com"
}

Сервер обновит информацию о пользователе, но если мы снова отправим тот же запрос, состояние останется неизменным. Таким образом, идемпотентность позволяет избежать неожиданных изменений и обеспечивает стабильность работы API.

Важно отметить, что не все методы HTTP являются идемпотентными. Например, метод POST, используемый для создания новых ресурсов, не является идемпотентным, так как каждый вызов создает новый ресурс. Поэтому при проектировании API необходимо четко разделять идемпотентные и неидемпотентные методы для обеспечения корректности обработки запросов.