Idempotentie

Een netwerk kan een antwoord kwijtraken nadat het werk al gedaan is. Probeer je een POST zonder bescherming opnieuw, dan krijgt de klant misschien twee uitnodigingen, of nodig je een teamlid twee keer uit. Elke POST van de API draagt daarom een Idempotency-Key: stuur dezelfde sleutel nog eens en je krijgt het eerste antwoord terug in plaats van een tweede actie.

Verplicht bij elke POST

• Zonder de header is het antwoord een 400 errors.api.idempotencyKeyRequired.
• Een sleutel langer dan 255 tekens is een 400 errors.api.idempotencyKeyTooLong.
• Ook het opnieuw versturen van de uitnodiging van een teamlid vraagt een sleutel: een herhaalde verzending zou twee keer mailen.

Eén sleutel per actie van de gebruiker

• Maak een UUID op het moment dat de gebruiker iets doet — de klik in je CRM — en bewaar hem bij die actie in je systeem. Gebruik hem alleen opnieuw om datzelfde verzoek te herhalen.
• Een sleutel hoort bij je API-sleutel en het endpoint, en is gebonden aan het verzoek. Dezelfde sleutel op een ander pad (het opnieuw versturen van een andere uitnodiging) of met een andere body is een 422 errors.api.idempotencyKeyReused.
• Herhaal met dezelfde API-sleutel. Een herhaling met een andere sleutel wordt opnieuw uitgevoerd; zie de stappen voor vervangen onder Authenticatie.

De voorbeelden in dit hoofdstuk zetten de sleutel op een eigen regel:

IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST https://api.schedulinq.com/api/v1/users \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "piet+ov@loodgieter-bakker.example", "firstName": "Piet", "lastName": "Bakker", "roleId": "3f0c8a52-6b1e-4d7a-9c3e-1a2b3c4d5e04"}'

Om het opnieuw te proberen voer je de regel met curl opnieuw uit, niet de toewijzing: dezelfde sleutel herhaalt dan in plaats van twee keer aan te maken.

De antwoorden

• Dezelfde sleutel met hetzelfde verzoek, zodra het eerste klaar is: de bewaarde status en body, met de header Idempotent-Replayed: true en een nieuwe requestId.
• Dezelfde sleutel met een ander verzoek: een 422 errors.api.idempotencyKeyReused.
• Dezelfde sleutel terwijl de eerste aanroep nog loopt: een 409 errors.api.duplicateRequestInProgress. Probeer het na een moment opnieuw, met dezelfde sleutel.
• Een eerste aanroep die na 60 seconden nog niet klaar is, mag door een herhaling worden overgenomen.

Wat wordt bewaard, en wat dat betekent voor een herhaling

Bewaard en 24 uur lang herhaald: elke 2xx, en elke definitieve weigering — 400, 402, 403, 404, 409 (behalve de twee hieronder) en 422. Heb je de oorzaak van een bewaarde weigering opgelost — een beheerder heeft een plaats toegevoegd, een teamlid is geactiveerd, je hebt het verzoek verbeterd — stuur dan een nieuwe sleutel. Dezelfde sleutel zou de oude weigering herhalen.

Niet bewaard: een 409 errors.api.duplicateRequestInProgress, een 409 errors.api.conflict (tegelijk door een ander verzoek gewijzigd), 408, 425, 429 en elke 5xx. Probeer die opnieuw met dezelfde sleutel.

Bewaarde antwoorden worden versleuteld, omdat er links in kunnen staan.

Veelgestelde vragen

Kan ik dezelfde sleutel voor twee verschillende klanten gebruiken?

Nee. Eén sleutel is één actie. Het tweede verzoek wordt geweigerd met een 422 errors.api.idempotencyKeyReused.

Hebben GET-verzoeken een sleutel nodig?

Nee. Lezen verandert niets, dus een GET mag je zo vaak herhalen als je wilt.