Salt la conținutul principal

Operații de scriere care modifică o resursă existentă

Nu este implicat niciun header. Acolo unde o repetare returna anterior o eroare, acum returnează starea curentă: O repetare nu scrie nimic, iar răspunsul ei conține Idempotent-Replayed: true — prin acel header faci diferența între „am anulat-o eu” și „era deja anulată”. Trei excepții returnează în schimb 409:
  • Activarea cu un activated_at diferit. Momentul recoltării apare pe raportul de laborator, așa că o reîncercare nu trebuie să îl suprascrie silențios.
  • Anularea unei programări deja anulate cu un cancellation_reason diferit. Același raționament: motivul înregistrat poate să fi fost corectat între timp, iar o reîncercare nu trebuie să îl suprascrie. Retrimite motivul înregistrat sau omite-l.
  • Anularea după punctul fără întoarcere — o recoltare de sânge confirmată, o expediere preluată, un kit expediat sau activat.
Trei endpoint-uri nu sunt în mod intenționat sigure la reîncercare:

Operații de scriere care creează ceva

Cinci endpoint-uri acceptă un header opțional Idempotency-Key, de cel mult 255 de caractere: O cheie, patru încercări, o comandă — ce primești înapoi depinde de momentul în care reîncerci și dacă corpul cererii coincide: Diagramă de secvență: un duplicat trimis la 350 ms după prima cerere primește 409 cât timp acea cerere rulează încă, prima returnează 201, o reîncercare ulterioară cu aceeași cheie returnează aceeași comandă marcată cu Idempotent-Replayed, iar aceeași cheie cu un corp modificat returnează 409. Diagramă de secvență: un duplicat trimis la 350 ms după prima cerere primește 409 cât timp acea cerere rulează încă, prima returnează 201, o reîncercare ulterioară cu aceeași cheie returnează aceeași comandă marcată cu Idempotent-Replayed, iar aceeași cheie cu un corp modificat returnează 409. Cheile sunt limitate la cheia ta API și la endpoint, astfel încât nu intră niciodată în conflict cu cele ale altui partener sau cu aceeași cheie folosită în altă parte.
  • Aceeași cheie, același corp → timp de 24 de ore primești înapoi răspunsul original, marcat cu Idempotent-Replayed: true. Ordinea câmpurilor și spațiile albe nu contează.
  • Aceeași cheie, corp diferit → 409.
  • Un Idempotency-Key gol → 400, în loc să fie ignorat.

Când este eliberată cheia

Crearea nu este atomică — un 5xx nu înseamnă că nu s-a scris nimic.
  • Cererea a eșuat înainte să se creeze ceva → cheia este eliberată, așa că poți reîncerca folosind-o.
  • Cererea a eșuat după ce s-a creat ceva sau nu a returnat deloc un răspuns → cheia rămâne rezervată, iar reîncercările primesc 409. Preia resursa pentru a verifica dacă există, apoi folosește o cheie nouă dacă nu există.
O reluare returnează corpul răspunsului înregistrat la crearea resursei — un snapshot, nu o citire în timp real. Dacă resursa s-a modificat între timp, preia-o direct.

Unele operații de creare au și o cheie naturală

Două endpoint-uri resping duplicatele de la sine, independent de orice header:
  • Creează programare permite o singură programare per profil, locație și moment. O repetare returnează 409 cu appointment_id-ul existent.
  • Creează profil returnează 409 când email are deja un profil. Dacă omiți email, se generează un placeholder unic pentru fiecare cerere, așa că repetările chiar creează profiluri separate.
Când se aplică ambele, vei vedea codul 409 al cheii naturale și doar acesta conține câmpul suplimentar (appointment_id sau un discriminator error_name) — un 409 de idempotență conține doar error, așa că citește acele câmpuri defensiv.