Операції запису, що змінюють наявний ресурс
Жоден заголовок не потрібен. Там, де повторний запит раніше повертав помилку, тепер він повертає поточний стан:
Повторний запит нічого не записує, а його відповідь містить
Idempotent-Replayed: true — цей заголовок дозволяє відрізнити «я це скасував» від «це вже було скасовано».
Натомість три винятки повертають 409:
- Активація з іншим
activated_at. Час збору зразка потрапляє до лабораторного звіту, тому повторна спроба не повинна непомітно його перезаписувати. - Скасування вже скасованого запису з іншим
cancellation_reason. Та сама логіка: записану причину могли вже виправити, і повторна спроба не повинна її перезаписувати. Надішли записану причину ще раз або пропусти це поле. - Скасування після точки неповернення — підтверджений забір крові, забране відправлення, відправлений або активований набір.
- Підтвердити забір крові — другий виклик повертає
409. - Надіслати результати електронною поштою (
POST /v1/appointments/{id}/results/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, тому читай ці поля обережно.