HTTP-заголовок Idempotency-Key запроса можно использовать, чтобы сделать запросы POST и PATCH идемпотентными.

Это позволяет клиентам повторно отправлять запросы, подтверждение получения которых не было получено, не беспокоясь о том, что сервер уже получил и обработал запрос.

Синтаксис

Idempotency-Key: <key>

Директивы

<key>

Уникальный ключ для конкретного запроса. Формат определяется сервером.

Описание

Методы HTTP GET, HEAD, PUT, DELETE и OPTIONS являются идемпотентными. Это означает, что можно отправлять сообщение с помощью этих методов любое количество раз, и состояние сервера либо не изменится, либо будет изменяться одинаковым образом при каждом получении сообщения. Например, если отправить одно и то же сообщение PUT несколько раз, при каждой отправке на сервер будет обновляться один и тот же ресурс с одним и тем же значением.

Методы POST и PATCH не являются идемпотентными, а это значит, что состояние сервера может изменяться при каждом получении сообщения. В отличие от сообщения PUT, при многократной отправке одного и того же запроса POST сервер может создавать новый ресурс для каждого успешно обработанного запроса. Аналогично, PATCH отражает изменение относительно определённого состояния, а это состояние изменяется при каждом применении патча.

Идемпотентность важна в случаях, когда клиент не получает ответ, поскольку она позволяет клиенту безопасно повторно отправить запрос, не беспокоясь о возможных побочных эффектах.

Заголовок HTTP Idempotency-Key позволяет клиенту сделать запросы POST и PATCH идемпотентными, присваивая им уникальный идентификатор (ключ). Затем клиент может отправлять один и тот же запрос несколько раз, а сервер будет знать, что действие следует выполнить только один раз.

Обязанности клиента

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

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

Обязанности сервера

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

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

Отпечаток идемпотентности

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

Чтобы защититься от повторного использования клиентами ключей для новых запросов, сервер может создавать и сохранять «отпечаток идемпотентности» запроса вместе с ключом. Это хеш всех или части запроса, который можно сравнить с другими запросами с тем же ключом.

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

Обработка запроса

Получив запрос POST или PATCH с Idempotency-Key к конечной точке, для которой он требуется, сервер должен проверить, получал ли он уже запрос с этим ключом.

• Если нет, сервер должен выполнить операцию, отправить ответ, а затем сохранить ключ.
• Если да, сервер не должен выполнять операцию, но должен ответить так, как будто выполнил её.

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

Если запрос получен без Idempotency-Key к конечной точке, для которой он требуется, сервер должен отправить ответ с ошибкой.

Ответы сервера с ошибками

Сервер должен отправлять ответы с ошибками в следующих случаях:

• 400 Bad Request: Заголовок отсутствует для конечной точки, для которой, согласно документации, он требуется.
• 409 Conflict: Запрос с тем же ключом в данный момент обрабатывается или всё ещё находится в обработке.
• 422 Unprocessable Content: Ключ уже используется для другого содержимого запроса (если поддерживается создание отпечатков идемпотентности).

В случае ответа 409 Conflict клиентам потребуется подождать перед повторной попыткой. При всех остальных ошибках клиентам нужно будет изменить запросы перед повторной отправкой.

Спецификация не устанавливает формат содержимого ответа с ошибкой, но ответы с ошибками должны содержать ссылку на документацию, специфичную для реализации и объясняющую ошибку. В качестве одного из вариантов можно использовать формат содержимого JSON, описанный в RFC 9457: сведения о проблемах для HTTP API. Например, следующий ответ можно использовать, если ключ отсутствует:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
    "type": "https://developer.example.com/idempotency/docs",
    "title": "Idempotency-Key is missing",
    "detail": "This operation is idempotent and requires correct usage of Idempotency Key.",
}

Примеры

Запрос POST с ключом

В следующем сообщении показан запрос POST для создания нового пользователя. Ключ 9c7d2b4a0e1f6c835a2d1b0f4e3c5a7d — это уникальное значение, соответствующее требованиям, опубликованным хостом (example.com не поддерживает этот заголовок, поэтому мы просто придумали значение).

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json
Idempotency-Key: 9c7d2b4a0e1f6c835a2d1b0f4e3c5a7d

{
  "user_id": "12345",
  "name": "Sharma Chow",
  "email": "sharmac@example.com"
}

Если ответ не получен, клиент может безопасно повторно отправить точно такой же запрос. Если сервер не получил предыдущий запрос, он обработает этот; если же предыдущий запрос уже был получен, второй запрос будет проигнорирован, но сервер ответит так, как если бы он обработал второй запрос обычным образом.

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

HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Content-Language: en

{
    "type": "https://example.com/idempotency/docs",
    "title": "Server processing previous request.",
    "detail": "A request with the same key is currently/still being processed.",
}

Спецификации

Совместимость с браузерами