Операции записи, которые изменяют существующий ресурс
Никаких заголовков не требуется. Там, где повторный запрос раньше возвращал ошибку, теперь возвращается текущее состояние:
Повторный запрос ничего не записывает, а его ответ содержит
Idempotent-Replayed: true — по этому заголовку ты отличишь «я отменил» от «уже было отменено».
Три исключения вместо этого возвращают 409:
- Активация с другим
activated_at. Время сбора попадает в лабораторный отчёт, поэтому повторный запрос не должен незаметно его перезаписывать. - Отмена уже отменённой записи с другим
cancellation_reason. Логика та же: записанную причину с тех пор могли исправить, и повторный запрос не должен её перезаписывать. Отправь записанную причину ещё раз или не передавай её. - Отмена после точки невозврата — подтверждённый забор крови, забранное отправление, отправленный или активированный набор.
- Подтверждение забора крови — повторный вызов возвращает
409. - Отправка результатов по email (
POST /v1/appointments/{id}/results/email) и Отправка результатов по email (POST /v1/home-kit-orders/{id}/results/email) — каждый вызов отправляет одно письмо. Повторный запрос после таймаута или5xxможет отправить клиенту дубликат.
Операции записи, которые что-то создают
Пять эндпоинтов принимают необязательный заголовокIdempotency-Key длиной не более 255 символов:
- Создание профиля
- Создание записи
- Создание заказа набора для домашнего теста
- Создание отправления
- Загрузка документа
- Тот же ключ, то же тело → в течение 24 часов ты получаешь исходный ответ с пометкой
Idempotent-Replayed: true. Порядок полей и пробелы не имеют значения. - Тот же ключ, другое тело →
409. - Пустой
Idempotency-Key→400, а не игнорируется.
Когда ключ освобождается
Создание не атомарно —5xx не означает, что ничего не было записано.
- Запрос завершился ошибкой до того, как что-то было создано → ключ освобождается, и ты можешь повторить запрос с ним.
- Запрос завершился ошибкой после того, как что-то было создано, или вообще не вернул ответ → ключ остаётся занятым, а повторные попытки получают
409. Запроси ресурс, чтобы проверить, существует ли он, и используй новый ключ, если его нет.
Повторный запрос возвращает тело ответа, записанное при создании ресурса — снимок, а не
актуальные данные. Если ресурс с тех пор изменился, запроси его напрямую.
У некоторых операций создания также есть естественный ключ
Два эндпоинта отклоняют дубликаты самостоятельно, независимо от каких-либо заголовков:- Создание записи допускает одну запись на профиль, локацию и момент времени. Повторный запрос возвращает
409с существующимappointment_id. - Создание профиля возвращает
409, если дляemailуже существует профиль. Если не передаватьemail, для каждого запроса генерируется уникальная заглушка, поэтому повторные вызовы действительно создают отдельные профили.
409 по естественному ключу, и только этот ответ содержит дополнительное поле (appointment_id или дискриминатор error_name) — ответ 409 по идемпотентности содержит только error, поэтому читай эти поля с проверкой их наличия.