Naar hoofdinhoud gaan

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.
Drie endpoints zijn bewust niet veilig om te herhalen:
  • Bloedafname bevestigen — een tweede aanroep geeft 409 terug.
  • 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 een 5xx kan de klant een dubbele e-mail sturen.

Schrijfbewerkingen die iets aanmaken

Vijf endpoints accepteren een optionele Idempotency-Key-header van maximaal 255 tekens: Eén sleutel, vier pogingen, één bestelling — wat je terugkrijgt hangt af van wanneer je het opnieuw probeert en of de body overeenkomt: Sequentiediagram: een duplicaat dat 350 ms na het eerste verzoek wordt verstuurd, krijgt 409 terwijl dat verzoek nog loopt, het eerste geeft 201 terug, een latere herhaling met dezelfde sleutel geeft dezelfde bestelling terug met de markering Idempotent-Replayed en dezelfde sleutel met een gewijzigde body geeft 409 terug. Sequentiediagram: een duplicaat dat 350 ms na het eerste verzoek wordt verstuurd, krijgt 409 terwijl dat verzoek nog loopt, het eerste geeft 201 terug, een latere herhaling met dezelfde sleutel geeft dezelfde bestelling terug met de markering Idempotent-Replayed en dezelfde sleutel met een gewijzigde body geeft 409 terug. Sleutels zijn gekoppeld aan je API-sleutel en aan het endpoint, zodat ze nooit botsen met die van een andere partner of met dezelfde sleutel die elders wordt gebruikt.
  • 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 — een 5xx 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 409 terug met de bestaande appointment_id.
  • Profiel aanmaken geeft 409 terug wanneer email al een profiel heeft. Laat je email weg, dan wordt per verzoek een unieke placeholder gegenereerd, zodat herhalingen wel aparte profielen aanmaken.
Wanneer beide van toepassing zijn, krijg je de 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.