Koppelingen die blijven werken

Een koppeling bouwen is meestal een middag werk. Een koppeling bouwen die over twee jaar nog betrouwbaar is, is iets anders — en dat verschil wordt pas zichtbaar op het moment dat de andere kant iets doet wat u niet had verwacht.

Dit artikel gaat over wat er misgaat bij API-koppelingen, en over de drie voorzieningen die dat opvangen: een wachtrij ertussen, verstandige herhaalpogingen en bewaking die alarm slaat voordat de klant dat doet.

Koppelingen falen, en niet netjes

De storing die iedereen verwacht — de andere kant is onbereikbaar — is juist de makkelijkste. Die is duidelijk en direct te herkennen. De vervelende storingen zijn de dubbelzinnige:

• De aanroep faalt niet, maar duurt dertig seconden. De gebruiker klikt nog eens, en er staan twee opdrachten klaar.
• De helft van een reeks is verwerkt en de andere helft niet, zonder dat ergens vastligt welke helft.
• Een veld dat altijd gevuld was, is nu soms leeg. Er is geen nieuwe versie uitgebracht; het gedrag is stilletjes veranderd.
• Dezelfde webhook komt twee keer binnen, omdat de verzender niet op tijd een bevestiging kreeg. Zonder maatregel staat de order er twee keer in.

Zet er een wachtrij tussen

De belangrijkste beslissing is om een externe aanroep nooit onderdeel te maken van het verzoek van de gebruiker. Is een order pas opgeslagen nadat het boekhoudpakket heeft geantwoord, dan is de beschikbaarheid van uw systeem gelijk aan die van het traagste systeem waaraan het hangt.

Met een wachtrij ertussen slaat het systeem eerst op wat het zelf weet, en verwerkt het de koppeling daarna. De gebruiker merkt een storing bij de andere partij niet, de opdracht raakt niet kwijt, en herstel na uitval is een kwestie van de wachtrij laten leeglopen in plaats van handmatig nalopen wat er ontbreekt.

Herhalen zonder schade aan te richten

Opnieuw proberen is de standaardoplossing en tegelijk een veelvoorkomende oorzaak van dubbele boekingen en overbelaste leveranciers. Vier regels houden het veilig:

1. Stuur bij elke opdracht een eigen sleutel mee, zodat dezelfde opdracht twee keer versturen niet twee keer verwerkt wordt. Ondersteunt de andere kant dat niet, houd dan zelf bij wat er al verstuurd is.
2. Wacht steeds langer tussen pogingen, met een willekeurige marge erbij. Zonder die marge komen alle wachtende opdrachten na een storing tegelijk binnen en ligt de leverancier opnieuw plat.
3. Leg vast hoe vaak en hoe lang u het probeert. Eeuwig herhalen is geen veerkracht; dat is een storing die niemand meer opmerkt.
4. Wat definitief mislukt gaat naar een aparte lijst, met de volledige context erbij. Die lijst is de plek waar een mens naar kijkt, en hij hoort leeg te zijn.

Bewaking die iets zegt

De meeste koppelingen worden op de verkeerde manier bewaakt: er komt een melding zodra een aanroep faalt. Dat is te laat en tegelijk te veel. Een enkele mislukte aanroep die daarna slaagt is geen probleem, en twintig meldingen per week zorgen ervoor dat de eenentwintigste genegeerd wordt.

Meet niet of een aanroep faalde, maar of het werk af is. Dat is de vraag waar de organisatie wakker van ligt.

Concreet: bewaak de lengte van de wachtrij, de leeftijd van het oudste openstaande bericht en het aantal items op de foutlijst. Loopt de achterstand op, dan is er iets aan de hand — ongeacht of individuele aanroepen slaagden. Dat zijn drie getallen, en samen vertellen ze meer dan een logboek vol foutmeldingen.

Kort samengevat

Haal externe aanroepen uit het verzoek van de gebruiker, maak opdrachten herhaalbaar zonder dubbele verwerking, en bewaak de achterstand in plaats van losse fouten. Dat is het verschil tussen een koppeling die een storing overleeft en een koppeling waarbij iemand een middag gaat rechtzetten wat er misging.