Idempotency

Voorkom dubbele objecten bij netwerkfouten door POST-requests een Idempotency-Key mee te geven.

Het probleem

Je stuurt een POST om een factuur aan te maken, maar de verbinding valt weg voordat je de response ziet. Is de factuur nu aangemaakt of niet? Zonder idempotency moet je gokken: opnieuw proberen kan een dubbele factuur opleveren.

De oplossing

Geef elke POST een unieke Idempotency-Key header mee, bijvoorbeeld een UUID die je zelf genereert:

bash

curl -sS -X POST https://api.appficient.nl/v1/invoices \
  -H "Authorization: Bearer apf_jouw_key_hier" \
  -H "Idempotency-Key: 5f3c1a9e-8b2d-4c7e-9f1a-2d3b4c5e6f7a" \
  -H "Content-Type: application/json" \
  -d '{ "client_guid": "...", "title": "..." }'

Stuur je hetzelfde request nog een keer met dezelfde key, dan krijg je exact dezelfde response terug en wordt er niets dubbel aangemaakt. Bij een replay zet de API de header X-Idempotent-Replay: true.

Regels

Werkt op POST-endpoints die de header ondersteunen. GET, PATCH en DELETE zijn van zichzelf veilig om te herhalen.
Gebruik per logische actie één key. Nieuwe actie, nieuwe key.
Keys blijven 24 uur geldig (cached).