Перейти к основному содержанию

Операции записи, которые изменяют существующий ресурс

Никаких заголовков не требуется. Там, где повторный запрос раньше возвращал ошибку, теперь возвращается текущее состояние: Повторный запрос ничего не записывает, а его ответ содержит Idempotent-Replayed: true — по этому заголовку ты отличишь «я отменил» от «уже было отменено». Три исключения вместо этого возвращают 409:
  • Активация с другим activated_at. Время сбора попадает в лабораторный отчёт, поэтому повторный запрос не должен незаметно его перезаписывать.
  • Отмена уже отменённой записи с другим cancellation_reason. Логика та же: записанную причину с тех пор могли исправить, и повторный запрос не должен её перезаписывать. Отправь записанную причину ещё раз или не передавай её.
  • Отмена после точки невозврата — подтверждённый забор крови, забранное отправление, отправленный или активированный набор.
Три эндпоинта намеренно не безопасны для повторных вызовов:

Операции записи, которые что-то создают

Пять эндпоинтов принимают необязательный заголовок Idempotency-Key длиной не более 255 символов: Один ключ, четыре попытки, один заказ — что ты получишь в ответ, зависит от того, когда ты повторяешь запрос и совпадает ли тело: Диаграмма последовательности: дубликат, отправленный через 350 ms после первого запроса, получает 409, пока тот ещё выполняется, первый возвращает 201, более поздний повтор с тем же ключом возвращает тот же заказ с пометкой Idempotent-Replayed, а тот же ключ с изменённым телом возвращает 409. Диаграмма последовательности: дубликат, отправленный через 350 ms после первого запроса, получает 409, пока тот ещё выполняется, первый возвращает 201, более поздний повтор с тем же ключом возвращает тот же заказ с пометкой Idempotent-Replayed, а тот же ключ с изменённым телом возвращает 409. Ключи привязаны к твоему API-ключу и к эндпоинту, поэтому они никогда не пересекаются с ключами другого партнёра или с тем же ключом, использованным в другом месте.
  • Тот же ключ, то же тело → в течение 24 часов ты получаешь исходный ответ с пометкой Idempotent-Replayed: true. Порядок полей и пробелы не имеют значения.
  • Тот же ключ, другое тело → 409.
  • Пустой Idempotency-Key → 400, а не игнорируется.

Когда ключ освобождается

Создание не атомарно — 5xx не означает, что ничего не было записано.
  • Запрос завершился ошибкой до того, как что-то было создано → ключ освобождается, и ты можешь повторить запрос с ним.
  • Запрос завершился ошибкой после того, как что-то было создано, или вообще не вернул ответ → ключ остаётся занятым, а повторные попытки получают 409. Запроси ресурс, чтобы проверить, существует ли он, и используй новый ключ, если его нет.
Повторный запрос возвращает тело ответа, записанное при создании ресурса — снимок, а не актуальные данные. Если ресурс с тех пор изменился, запроси его напрямую.

У некоторых операций создания также есть естественный ключ

Два эндпоинта отклоняют дубликаты самостоятельно, независимо от каких-либо заголовков:
  • Создание записи допускает одну запись на профиль, локацию и момент времени. Повторный запрос возвращает 409 с существующим appointment_id.
  • Создание профиля возвращает 409, если для email уже существует профиль. Если не передавать email, для каждого запроса генерируется уникальная заглушка, поэтому повторные вызовы действительно создают отдельные профили.
Когда срабатывают оба механизма, ты получишь 409 по естественному ключу, и только этот ответ содержит дополнительное поле (appointment_id или дискриминатор error_name) — ответ 409 по идемпотентности содержит только error, поэтому читай эти поля с проверкой их наличия.