Schrijfbewerkingen die een bestaande resource wijzigen
Hier is geen header voor nodig. Waar een herhaling vroeger een fout teruggaf, geeft deze nu de huidige status terug:
Een herhaling schrijft niets weg en de response bevat
Idempotent-Replayed: true — met die header onderscheid je “ik heb het geannuleerd” van “het was al geannuleerd”.
Drie uitzonderingen geven in plaats daarvan 409 terug:
- Activeren met een andere
activated_at. Het afnametijdstip staat op het labrapport, dus een nieuwe poging mag dit niet stilzwijgend overschrijven. - Een al geannuleerde afspraak annuleren met een andere
cancellation_reason. Zelfde redenering: de vastgelegde reden kan intussen zijn gecorrigeerd en een nieuwe poging mag die niet overschrijven. Stuur de vastgelegde reden opnieuw mee, of laat die weg. - Annuleren na het onomkeerbare punt — een bevestigde bloedafname, een opgehaalde zending, een verzonden of geactiveerde kit.
- Bloedafname bevestigen — een tweede aanroep geeft
409terug. - Resultaten e-mailen (
POST /v1/appointments/{id}/results/email) en Resultaten e-mailen (POST /v1/home-kit-orders/{id}/results/email) — elke aanroep verstuurt één e-mail. Een nieuwe poging na een time-out of een5xxkan de klant een dubbele e-mail sturen.
Schrijfbewerkingen die iets aanmaken
Vijf endpoints accepteren een optioneleIdempotency-Key-header van maximaal 255 tekens:
- Profiel aanmaken
- Afspraak aanmaken
- Thuistestkit-bestelling aanmaken
- Zending aanmaken
- Document uploaden
- Dezelfde sleutel, dezelfde body → gedurende 24 uur krijg je de oorspronkelijke response terug, met
Idempotent-Replayed: true. Veldvolgorde en witruimte maken niet uit. - Dezelfde sleutel, andere body →
409. - Een lege
Idempotency-Key→400, in plaats van genegeerd te worden.
Wanneer de sleutel wordt vrijgegeven
Aanmaken is niet atomair — een5xx betekent niet dat er niets is weggeschreven.
- Het verzoek is mislukt voordat er iets werd aangemaakt → de sleutel wordt vrijgegeven, dus je kunt het daarmee opnieuw proberen.
- Het verzoek is mislukt nadat er iets werd aangemaakt, of gaf helemaal geen antwoord terug → de sleutel blijft geclaimd en nieuwe pogingen krijgen
409. Haal de resource op om te controleren of deze bestaat en gebruik een nieuwe sleutel als dat niet zo is.
Een herhaling geeft de response-body terug die is vastgelegd toen de resource werd aangemaakt — een
momentopname, geen actuele versie. Als de resource sindsdien is gewijzigd, haal deze dan direct op.
Sommige aanmaakbewerkingen hebben ook een natuurlijke sleutel
Twee endpoints weigeren zelf duplicaten, los van enige header:- Afspraak aanmaken staat één afspraak per profiel, locatie en tijdstip toe. Een herhaling geeft
409terug met de bestaandeappointment_id. - Profiel aanmaken geeft
409terug wanneeremailal een profiel heeft. Laat jeemailweg, dan wordt per verzoek een unieke placeholder gegenereerd, zodat herhalingen wel aparte profielen aanmaken.
409 van de natuurlijke sleutel en alleen die bevat het extra veld (appointment_id, of een error_name-discriminator) — een idempotency-409 bevat alleen error, dus lees die velden defensief uit.