Idempotentie
- Troy Verhelst
- David Op de Beeck
Context
Idempotentie is een eigenschap die dicteert dat het mogelijk is om een operatie veilig meerdere keren opnieuw uit te voeren, waarbij elke keer hetzelfde resultaat wordt verkregen, en zonder dat dit enige extra bijwerkingen in het systeem heeft veroorzaakt.
Voorbeeld scenario
Een client probeert via de API een dossier aan te maken, maar dit faalt omwille van een technisch probleem (bvb een timeout). De client heeft in dit scenario geen antwoord ontvangen van de API en heeft dus geen zekerheid dat het dossier is aangemaakt. Als de client dezelfde request hierna opnieuw verstuurt zal het dossier potentieel 2 keer aangemaakt worden.
Idempotente HTTP-werkwoorden
De HTTP-specificatie schrijft voor dat de werkwoorden GET, PUT en DELETE inherent idempotent zijn. De API respecteert deze richtlijnen en het is veilig om requesten met deze werkwoorden meerdere keren opnieuw uit te voeren.
Idempotentie sleutels
De POST- en PATCH-werkwoorden zijn niet idempotent, dus er is extra werk nodig om het gebruik ervan idempotent veilig te maken.
Gebruik
De API accepteert een Idempotency-Key header van clients die een string-waarde bevat en een request op unieke wijze identificeert. In het geval van een timeout of een ander technisch probleem kan de client de request opnieuw versturen met dezelfde waarde in de Idempotency-Key header. Afhankelijk van het resultaat van de initiële request zal de API de nieuwe request voor de eerste keer verwerken of het resultaat van de initiële request teruggeven.
Het gebruik van de Idempotency-Key header heeft als gevolg dat niet-idempotente POST en PATCH veilig zijn voor idempotent gebruik.
Uniekheid
De idempotentie sleutels moeten uniek zijn voor alle requesten naar hetzelfde API-pad. We stellen voor dat clients deze vereiste implementeren door het gebruik van UUID versie 4 (random) als waarde van de Idempotency-Key header.
Geldigheid
Een idempotentie sleutel en bijhorende resultaat wordt gedurende 24u bijgehouden. Als deze tijdsspanne is verstreken worden ze verwijderd uit het systeem.
Aanbevelingen voor het opnieuw versturen van requesten
Onderstaande tabel toont enkele veelvoorkomende statuscodes die u kunt terugkrijgen en geeft aanbevelingen voor nieuwe pogingen.
Statuscodes | Aanbeveling | Opmerking |
|---|---|---|
200, 201 | NIET opnieuw proberen | De oorspronkelijke request is succesvol voltooid. Nieuwe pogingen zullen ook succesvol terugkeren. |
400-serie | NIET opnieuw proberen | Er is een probleem met de request:
Als de request betrekking heeft op een resource die achterliggend kan wijzigen, kan het opnieuw proberen van de request mogelijk slagen. |
500-serie | WEL opnieuw proberen | De fout wordt veroorzaakt door een serverprobleem en is over het algemeen van voorbijgaande aard. Herhaal het verzoek met een geschikte uitstel strategie. |
Exponentiële uitstel strategie
We stellen voor dat clients gebruik maken van een exponentiële uitstel strategie bij het opnieuw proberen van requesten. Vertragingen tussen nieuwe pogingen worden in de loop van de tijd steeds langer in plaats van vast of willekeurig te zijn. Deze strategie geeft ruimte aan tijdelijke problemen om zichzelf op te lossen en voorkomt tegelijkertijd een overbelasting van de API.
Referenties
https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html