Перейти до основного вмісту

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

Жоден заголовок не потрібен. Там, де повторний запит раніше повертав помилку, тепер він повертає поточний стан: Повторний запит нічого не записує, а його відповідь містить 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, тому читай ці поля обережно.