Note |
---|
Dit is de aangepaste werking omtrent idempotentie binnen de API die beschikbaar is op productie vanaf 17/04. |
Table of Contents | ||
---|---|---|
|
Context
Idempotentie is een eigenschap van een operatie die dicteert dat het mogelijk is om die 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 HTTP request aanmaken van een dossier faalt omwille van een technisch probleem (bvb een timeout). De client heeft in dit scenario geen antwoord ontvangen en heeft dus geen zekerheid dat de request niet is verwerkt door het VHP. Als het dossier is aangemaakt door de API. Als de client dezelfde request hierna opnieuw geprobeerd word met een andere idempotency key verstuurd zal het dossier 2x bestaanpotentieel 2 keer aangemaakt worden door de API.
Gebruik
Bij POST calls wordt verwacht dat er een header wordt meegestuurd genaamd idempotency-key
. We raden aan om als waarde een UUID v4 mee te geven, maar in principe moet dit een unieke waarde zijn per request die uitgevoerd wordt.
Wat is een idempotency key?
An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.
Deze dient dus om duplicate request te voorkomen. Het VHP gebruikt de idempotency key om het onderscheid te maken tussen een nieuwe request en de retry van een vorige request.
Als de idempotency key nog niet is gebruikt dan wordt de request als nieuw beschouwt en zal de logica achter het endpoint aangeroepen worden.
Als de idempotency key in een vorige request is gebruikt dan zal de originele response teruggegeven worden en zal de logica achter het endpoint niet aangeroepen worden.
De idempotency key moet verschillend zijn per request, we stellen voor dat de aansluiters UUID v4 gebruiken voor het genereren van de key. Enkel als dezelfde request opnieuw word geprobeerd moet dezelfde idempotency key gebruikt worden.
...
Idempotente HTTP-methodes
De HTTP-specificatie schrijft voor dat de werkwoorden GET
, PUT
en DELETE
inherent idempotent zijn. De VHP API respecteert deze richtlijnen en het is veilig om requesten met deze werkwoorden een aantal 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 VHP 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) voor de waarde van de Idempotency-Key
header.
Geldigheid
De idempotentie sleutels en het bijhorende resultaat worden gedurende 24u bijgehouden. Als deze tijdsspanne is verstreken worden ze verwijderd.
Aanbevelingen voor het opnieuw versturen van requesten
De onderstaande tabel toont enkele veelvoorkomende statuscodes die u kunt krijgen op idempotente API-requesten 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 uitstelstrategie. |
Exponentiële uitstelstrategie
We stellen voor dat clients gebruik maken van een exponentiële uitstelstrategie 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