Idempotentie

Wat is idempotentie?

Een operatie is idempotent als het resultaat hetzelfde is, of je hem nu één keer of honderd keer uitvoert. Stuur je een PUT-request naar /users/42 met een bepaalde body, dan eindigt de server in dezelfde toestand of je dat verzoek nu één of vijftig keer doet. Stuur je daarentegen een betaalverzoek dat elke keer een charge aanmaakt, dan is hij niet idempotent.

Het concept komt uit de wiskunde: een functie f heet idempotent als f(f(x)) = f(x). Tweemaal toepassen geeft hetzelfde resultaat als eenmaal. In software-systemen is dat de eigenschap die maakt dat je veilig kan retryen wanneer een antwoord niet binnenkomt.

HTTP RFC 9110 verankert het formeel: GET, HEAD, PUT, DELETE, OPTIONS en TRACE zijn per definitie idempotent. POST is dat niet, tenzij de server expliciet idempotency-tokens ondersteunt.

Waarom heb je idempotentie nodig?

Netwerken zijn onbetrouwbaar. Op een gegeven moment stuur je een verzoek en krijg je geen antwoord. Was het verzoek verloren onderweg, was het antwoord verloren, of heeft de server het verwerkt en is alleen de bevestiging weg? Daar valt zonder retry geen uitspraak over te doen.

Zonder idempotentie loop je in elke retry-loop tegen een dilemma: stop je en accepteer je dat verzoeken misschien niet aankomen (at-most-once), of retry je en accepteer je dat ze soms dubbel uitgevoerd worden (at-least-once)? In een systeem zonder idempotente operaties moet je kiezen.

Met idempotentie verdwijnt het dilemma: at-least-once bezorging plus idempotente apply geeft je de facto exactly-once semantiek. Daarom duikt idempotentie op in elke laag waar onbetrouwbare bezorging speelt: webhooks (de afzender retryt tot je 200 OK teruggeeft), message queues (Kafka, SQS leveren minstens één keer), payment-API's (Stripe en Adyen verwachten dat je idempotency keys gebruikt), ETL / ELT-pipelines en Change Data Capture-streams.

Hoe maak je een operatie idempotent?

Vijf patronen, gegroeid uit decennia distributed-systems werk:

Idempotency keys
De client genereert per logische operatie een unieke key (typisch een UUID). De server slaat het eerste resultaat op onder die key en geeft bij volgende requests met dezelfde key dat opgeslagen resultaat terug, zonder de operatie opnieuw uit te voeren. Stripe documenteert dit pattern het breedst, AWS gebruikt het in vrijwel elke service, Kafka's "exactly-once producers" leunen erop.

Natuurlijke unieke key + upsert
Werk je met een entiteit die al een logische identifier heeft (klant-e-mail, order-nummer, externe ID), gebruik die als sleutel en doe upserts in plaats van inserts. Een tweede sync van dezelfde records doet dan niets nieuw, hij overschrijft met dezelfde waarden. Bij Reverse ETL is dit het verschil tussen 50.000 dubbele leads in je CRM en een propere sync.

Dedup-tabel met seen-events
Houd een tabel bij van event-IDs die je al verwerkt hebt. Elk binnenkomend event check je tegen die tabel; staat hij er al, dan sla je over. Werkt goed voor event-streams waar je geen controle hebt over de upstream retry-logica.

Declarative state in plaats van delta
Schrijf SET status = 'paid' in plaats van INCREMENT payments_count. De eerste blijft hetzelfde resultaat geven bij elke retry, de tweede telt op bij elke retry. Hetzelfde principe achter Kubernetes' declaratieve apply.

Version checks en optimistic locking
Lees een versie of ETag samen met de data, en stuur die mee in de update. De server accepteert alleen als de versie nog klopt. Een retry op verouderde data faalt expliciet in plaats van stilletjes te overschrijven.

Waar moet je op letten bij idempotentie?

Idempotency keys hebben een TTL
Stripe houdt keys 24 uur bij, andere systemen variëren. Retry je daarna nog met dezelfde key, dan voert de server het gewoon opnieuw uit. Plan je retry-window onder die TTL.

Semantische equivalentie van parameters
Stripe valideert dat de parameters bij een retry overeenkomen met de originele request. Verschillen ze, dan krijg je een fout in plaats van een uitvoering, om verkeerd hergebruik te voorkomen. Niet elke API doet dat; behandel idempotency keys per logische operatie als onveranderlijk.

Niet alles is natuurlijk idempotent
Een mail tweemaal versturen blijft twee mails, een SMS tweemaal blijft twee SMSen. Voor dat soort acties moet je zelf een dedup-laag bouwen tussen de retry-logica en het verzendkanaal.

Logging en monitoring
Zonder een audit trail per idempotency key (request ontvangen, eerste verwerking, retry teruggevonden) kan je achteraf niet bewijzen dat dubbele retries echt geen dubbele effecten hadden. Bij een incident is dat vaak waar je dagen aan kwijt bent.

"Exactly-once"-claims zijn marketing
Geen distributed systeem levert exactly-once zonder een vorm van coordinatie (two-phase commits, transactionele outboxes, of het idempotency-pattern hierboven). Vendor-pagina's die "exactly-once delivery" beloven, bedoelen ofwel iets beperkter (alleen binnen één broker), ofwel iets dat onder de motorkap toch idempotency keys gebruikt. Lees de fine print.