Page Comparison

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 gewoon een unieke waarde zijn per call 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.

...

Table of Contents

style	none

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.

Excerpt

Aanbevelingen voor het opnieuw versturen van requesten

Note

Er staat een brekende change op de planning waarbij we concurrency exceptions zullen teruggeven met foutcode 409 in plaats van 500. Fouten met foutcode 409 zullen vanaf dan ook opnieuw geprobeerd moeten worden.

Voor meer info qua planning, raadpleeg /wiki/spaces/VH/pages/474316816

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:

Het bevat een parameter of parameter combinatie 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 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.