Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Note

Dit is de aangepaste werking omtrent idempotentie binnen de API die beschikbaar is op productie vanaf 17/04.

Table of Contents
stylenone

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:

  • Het bevat een parameter of parametercombinatie die niet geldig is.

  • Er wordt gebruik gemaakt van een actie waarvoor u geen machtigingen heeft.

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

https://docs.crunchybridge.com/api-concepts/idempotency

https://www.zenrows.com/blog/axios-retry#delay