Uitleg · Engineering
Wat is een idempotency key: en waarom je app er een nodig heeft
Elke offline-app beantwoordt vroeg of laat dezelfde vraag: wat gebeurt er als de gebruiker twee keer op «versturen» tikt, of het netwerk midden in een request wegvalt en de client het opnieuw probeert? Het antwoord is een klein mechanisme dat een idempotency key heet, hier is hoe het werkt, en hoe het er in onze eigen code uitziet.
Het probleem in één zin
Netwerken zijn onbetrouwbaar, dus moeten clients het opnieuw proberen. Retries betekenen dat dezelfde logische actie meer dan één keer aankomt. Zonder bescherming wordt «meer dan één keer» twee tijdregistraties, twee facturen, twee boekingen.
Let op wat het probleem niet is: het is niet «de gebruiker dubbelklikte». Gebruikers dubbelklikken wel, maar het gangbare geval is veel minder zichtbaar, een mobiele app op een bouwplaats verliest bereik, zet de instempel in de wachtrij, de server past hem toe, het antwoord gaat onderweg verloren en de app stuurt hem (terecht) opnieuw. Het duplicaat is het systeem dat werkt zoals bedoeld.
Het mechanisme
Een idempotency key is een unieke identifier die de client per logische actie genereert, niet per HTTP-request. De client hangt dezelfde key aan het oorspronkelijke request en aan elke retry van die actie. De server houdt bij welke keys hij heeft gezien. Komt een key twee keer aan, dan geeft de server het eerste resultaat terug in plaats van de mutatie twee keer uit te voeren.
Drie eigenschappen maken het werkend:
- De client bezit de key. Als de server hem zou uitgeven, zou een retry vóór het ontvangen ervan niet te herkennen zijn. De key wordt op het toestel aangemaakt, in onze mobiele apps een UUID op het moment dat de gebruiker stempelt, niet wanneer de netwerkcall afgaat.
- De registratie is een claim, geen resultaat. De server schrijft eerst de claim («deze key is van mij, uitkomst in behandeling») en muteert pas daarna. Een gelijktijdige retry vindt de claim en wacht op of herhaalt de oorspronkelijke uitkomst, hij kan er nooit een tweede mutatie onderdoor schuiven.
- De claim bindt de payload. Wij slaan bij de key een hash op van de actie en zijn genormaliseerde invoer. Dezelfde key, andere payload → een 409-conflict, geen stille overschrijving. Een retry mag alleen maar «hetzelfde nog een keer» betekenen.
Waar het in onze apps terugkomt
De mobiele stempelwachtrij van ArbeitszeitCheck draagt een clientRequestIdcodeclient_event_id mee door elke replay. TourCheck bindt hetzelfde contract aan code bij checkpoint-bevestigingen, waar een replay de hele claim, notitie, foto, tijdstempel, vergelijkt met de opgeslagen rij. De vervaldatum doet er net zoveel toe als de dedupe: onze claim-rijen leven zeven dagen, lang genoeg om een lang weekend zonder bereik te overbruggen, kort genoeg dat de tabel een wachtrij blijft en geen logboek.
De korte versie voor je eigen app
Als je API state muteert en je client kan het opnieuw proberen, en elke client kan het opnieuw proberen, heb je precies drie dingen nodig: een door de client gegenereerde key per actie, een claim-rij als eerste schrijfactie en een payload-hash zodat «dezelfde key» ook «dezelfde bedoeling» betekent. Dat is het hele patroon. Alles eromheen, replay-vensters, opschoningsjobs, conflict-statuscodes, is loodgieterswerk rond die drie toezeggingen.