Dubbele bestellingen bij het werken met een API: oorzaken en bescherming

Waarom duplicaten verschijnen na één actie

De eigenaar van een paneel kan één keer op een knop klikken en meerdere identieke bestellingen zien: voor abonnees, weergaven, reacties of een andere dienst. Meestal zit het probleem niet in de klik zelf, maar in de keten tussen de klant, de API, de database en de leverancier.

Vanuit het perspectief van de server is "één verzoek" niet altijd één. De klant heeft mogelijk geen antwoord ontvangen, de verzending herhaald, terwijl de eerste operatie al was opgeslagen. Soms wordt een bestelling één keer aangemaakt in de database van het paneel, maar twee keer naar de leverancier gestuurd. Dit zijn verschillende scenario's, en ze worden op verschillende manieren opgelost.

Een time-out betekent niet dat de bestelling niet is aangemaakt

De meest voorkomende oorzaak is dat de klant een beperkte tijd op een antwoord wacht. De server ontvangt het verzoek, maakt de bestelling aan, maar antwoordt later dan de ingestelde time-out. De klant beschouwt de operatie als mislukt en verstuurt deze opnieuw.

Als gevolg daarvan staat de eerste bestelling al in de database, en het tweede verzoek maakt er nog een aan. Dit gebeurt vooral bij een langzame reactie van een externe API, een overbelaste wachtrij of een onstabiele verbinding tussen services.

Een time-out zegt alleen iets over het ontbreken van een antwoord, niet over het ontbreken van verwerking van het verzoek.

Automatische herhalingen aan de kant van de klant

Bibliotheken voor HTTP-verzoeken, achtergrondtaken en integratieservices herhalen een verzoek vaak automatisch. De aanleiding kan een verbindingsfout zijn, een serverresponscode, een netwerkonderbreking of een te langzaam antwoord.

Herhaling op zich is nuttig: het vermindert het aantal verloren bestellingen bij tijdelijke storingen. Het nadeel van deze aanpak is dat zonder bescherming tegen herverwerking elke netwerkonstabiliteit in duplicaten verandert.

• de herhaling kan worden gestart in de code van de site of de bot;
• de taak kan opnieuw worden gestart door de wachtrij;
• het verzoek kan worden herhaald door een proxy of integratiemodule;
• de operator kan de bestelling handmatig opnieuw versturen na een fout.

Een herhaald verzoek komt eerder aan dan het eerste antwoord

Soms bereiken twee identieke verzoeken de API vrijwel gelijktijdig. Bijvoorbeeld: de gebruiker heeft het formulier twee keer verzonden, de frontend heeft de knop niet geblokkeerd, of een achtergrondtaak is opnieuw gestart voordat de eerste was voltooid.

Als de handler eerst controleert of de bestelling bestaat en deze vervolgens aanmaakt, kunnen twee parallelle operaties de controle tegelijkertijd doorstaan. Elk ziet dat de bestelling nog niet bestaat, en elk voegt een nieuw record toe.

Deze situatie wordt een raceconditie genoemd. Een eenvoudige voorafgaande controle in de code beschermt er niet volledig tegen. Het nadeel van een controle zonder beperking op databaseniveau is dat deze faalt onder parallelle belasting.

De bestelling is opgeslagen, maar het API-antwoord is verloren gegaan

Een verzoek doorloopt meerdere fasen: de server ontvangt de gegevens, maakt het record aan, plaatst de taak in de wachtrij, stuurt het antwoord. Een storing is tussen elk van deze fasen mogelijk. Bijvoorbeeld: de database heeft de aanmaak van de bestelling al bevestigd, maar de verbinding is verbroken voordat het antwoord aan de klant werd doorgegeven.

De klant weet niet of de bestelling is geaccepteerd en herhaalt de operatie. Een API zonder apart verificatiemechanisme beschouwt het verzoek als nieuw. In het logboek ziet het er vaak uit alsof de service "zelf" twee bestellingen heeft aangemaakt, terwijl er twee inkomende aanroepen waren.

Idempotentiesleutel voor het aanmaken van een bestelling

Voor aanmaakoperaties is een unieke idempotentiesleutel nodig. De klant genereert deze vóór de eerste verzending en stuurt hem mee met de bestelparameters. Bij een herhaling door een time-out of fout wordt dezelfde sleutel gebruikt.

De API slaat de sleutel op samen met het verwerkingsresultaat. Als een verzoek met een al bekende sleutel binnenkomt, maakt de server geen nieuwe bestelling aan, maar retourneert het resultaat van de eerste aanroep: de bestel-ID, de status of de eerder gevormde fout.

Eén sleutel moet overeenkomen met één bedrijfsoperatie, niet met één HTTP-verbinding.

Het nadeel van de methode is dat sleutels moeten worden opgeslagen, volgens regels moeten worden opgeschoond en aan de API-kant moeten worden gecontroleerd. Als bij elke herhaling een nieuwe sleutel wordt gegenereerd, werkt de bescherming niet. Als één sleutel voor verschillende bestellingen wordt gebruikt, worden sommige nieuwe operaties ten onrechte afgewezen.

Uniciteit moet door de database worden gecontroleerd

Idempotentie kan het beste worden aangevuld met een uniciteitsbeperking in de database. Hiervoor kiest men een combinatie die de bestelling eenduidig beschrijft: interne klant-ID, idempotentiesleutel, diensttype en andere benodigde velden.

De database moet het tweede record afwijzen, zelfs als twee handlers tegelijkertijd bij het aanmaken zijn gekomen. Na een conflict retourneert de API de bestaande bestelling, niet een fout zonder uitleg.

Het nadeel van een strikte uniciteitsbeperking is dat deze niet alleen op een link of gebruikersnaam mag worden gebaseerd. Een klant kan bewust meerdere keren dezelfde dienst voor hetzelfde kanaal bestellen. Een te brede beperking blokkeert normale herhaalaankopen.

Een wachtrij kan een taak meer dan één keer afleveren

Taakwachtrijen werken vaak volgens het principe "levering ten minste één keer". Als een worker de taak heeft verwerkt maar de voltooiing niet op tijd heeft bevestigd, kan de wachtrij dezelfde taak opnieuw aan een andere worker geven.

Voor de wachtrij is dit een normale manier om geen taak te verliezen. Voor het aanmaken van een bestelling zonder idempotentie is het een bron van duplicaten. De taak-ID of een aparte operatiesleutel moet worden doorgegeven aan de uiteindelijke handler, inclusief de module die de bestelling naar de leverancier stuurt.

Het nadeel van het uitschakelen van herhaalde levering is dat bij een crash van een worker een deel van de bestellingen kan verdwijnen. Veiliger is om mogelijke herhalingen te accepteren en de handler er bestendig tegen te maken.

Duplicaten ontstaan tussen het paneel en de leverancier

Een interne bestelling kan één keer worden aangemaakt, maar het verzoek aan de externe API twee keer worden verzonden. De oorzaak is dezelfde: het paneel heeft geen antwoord van de leverancier ontvangen en besloot de verzending te herhalen. Als de leverancier het eerste verzoek al had geaccepteerd, verschijnen er aan zijn kant twee identieke aanvragen.

Er is een aparte koppeling nodig tussen de interne bestelling en de externe: een verzend-ID, een idempotentiesleutel of het opgeslagen antwoord van de leverancier. Men mag niet aannemen dat bescherming bij de ingang van het eigen paneel automatisch de uitgaande aanroepen beschermt.

Het nadeel van afstemming met een externe API is dat niet elke leverancier zoeken op een externe sleutel ondersteunt. Dan moet men de verzendpogingen vastleggen en onbepaalde statussen apart analyseren.

Een webhook mag geen nieuwe bestelling aanmaken

Webhooks melden wijzigingen: bestelling geaccepteerd, gestart, voltooid, geannuleerd of vereist controle. De fout ontstaat wanneer de webhook-handler de melding opvat als een opdracht om de bestelling opnieuw aan te maken.

Dezelfde webhook kan opnieuw binnenkomen. De afzender herhaalt de levering als hij geen bevestiging heeft ontvangen, en meldingen komen soms niet in de juiste volgorde aan. De handler moet de bestaande bestelling vinden op basis van de externe ID en de status bijwerken.

Het nadeel van het alleen op ontvangsttijd verwerken van webhooks is dat een latere melding de actuele status kan overschrijven met een verouderde. Er zijn gebeurtenis-ID's, statusversies of duidelijke overgangsregels nodig.

Welke gegevens helpen de bron van duplicaten te vinden

Voor een onderzoek is het niet voldoende om alleen twee bestelnummers te zien. Er zijn gegevens nodig over elke verwerkingsfase: tijdstip van het verzoek, idempotentiesleutel, klant-ID, bestelparameters, nummer van de achtergrondtaak, antwoord van de externe API en pogingen tot opnieuw verzenden.

• koppel duplicaten aan de operatiesleutel, niet alleen aan de link;
• controleer of identieke verzoeken in het logboek van de inkomende API stonden;
• kijk of de taak in de wachtrij is herhaald;
• scheid het aanmaken van de interne bestelling van de verzending naar de leverancier;
• sla de externe aanvraag-ID op direct na ontvangst van het antwoord.

Het nadeel van te korte logs is dat de bron van het probleem verdwijnt voordat deze kan worden geanalyseerd. Het nadeel van overmatige logging is dat tokens, persoonsgegevens en andere gevoelige velden in het record kunnen terechtkomen, dus deze moeten worden gemaskeerd.

Hoe een onbepaald resultaat van een verzoek te verwerken

Na een time-out mag een bestelling niet direct opnieuw met nieuwe gegevens worden aangemaakt. Eerst moet de API de operatie controleren op basis van de idempotentiesleutel of de klant-ID. Als de bestelling is gevonden, wordt de huidige status ervan geretourneerd. Als de verwerking nog gaande is, ontvangt de klant een wachtstatus.

1. Genereer een operatiesleutel vóór het eerste verzoek.
2. Verstuur dezelfde sleutel bij elke herhaling.
3. Sla de sleutel en de bestelling op in één beveiligde databaseoperatie.
4. Geef de operatie-ID door aan de wachtrij en de externe API.
5. Retourneer de eerder aangemaakte bestelling bij een herhaalde aanroep.

Een dergelijk scenario vereist aanpassing van de API en de klantintegratie. Het nadeel is lastiger debuggen en meer bestelstatussen, maar herhaalde levering van een verzoek betekent niet langer automatisch een herhaalaankoop.