API-integraties 101: je bedrijfssystemen verbinden zonder een puinhoop te creëren

Elk bedrijf dat meer dan een paar stukken software draait, heeft er uiteindelijk behoefte aan dat ze met elkaar praten, en hoe dat wordt gebouwd bepaalt of je uiteindelijk een beheersbaar systeem krijgt of een kluwen die niemand twee jaar later nog volledig begrijpt. Het verschil zit meestal niet in de individuele integraties, het zit in het patroon waarin ze zijn gebouwd.

Punt-tot-punt-integratie, elk systeem rechtstreeks verbinden met elk ander systeem dat zijn data nodig heeft, is het natuurlijke eerste instinct en degene die het slechtst schaalt. Drie systemen hebben drie verbindingen nodig; vijf systemen hebben er tien nodig; tegen de tijd dat je bij acht of negen systemen bent, onderhoud je tientallen individuele integraties, elk met zijn eigen auth, zijn eigen eigenaardigheden, en zijn eigen faalscenario's, en één systeem toevoegen betekent verbindingen bouwen met verschillende bestaande systemen tegelijk.

Een hub-patroon, één centraal systeem dat het integratiepunt bezit, en elk ander systeem verbindt met die hub in plaats van met elkaar, verandert de rekensom volledig. Een nieuw systeem toevoegen betekent één verbinding bouwen, met de hub, geen verbindingen met alles waarmee het uiteindelijk data moet delen. Dit is hetzelfde onderliggende patroon dat een centraal ERP-systeem laat werken voor multichannel e-commerce: één bron van waarheid, al het andere een gesynchroniseerde verbinding ermee.

De onderdelen van integratiewerk die planningen daadwerkelijk laten ontsporen, zijn niet de happy-path datamapping, veld A in het ene systeem matchen met veld B in het andere is meestal het makkelijke deel. Het is authenticatie (API-sleutels die verlopen, OAuth-flows die vernieuwd moeten worden, roterende credentials), rate limits (een API van derden die je precies throttlet wanneer je het het hardst nodig hebt, meestal tijdens een bulksynchronisatie), en webhookbetrouwbaarheid (een event dat zou moeten afgaan maar dat af en toe niet doet, of twee keer afgaat). Budgetteer hier echt tijd voor, het zijn geen edge cases, het is de daadwerkelijke vorm van integratiewerk.

Idempotentie, de eigenschap dat hetzelfde event twee keer verwerken hetzelfde resultaat oplevert als het één keer verwerken, is geen geavanceerde optimalisatie, het is een basisvereiste voor alles gebouwd op webhooks of retries. Zonder dit kan een webhook die door een netwerkhaperingje twee keer afgaat een dubbele bestelling creëren, voorraad dubbel verlagen, of een dubbele melding versturen, en deze bugs zijn notoir lastig te vangen in tests omdat ze alleen opduiken onder echte netwerkomstandigheden.

Retry-logica verdient dezelfde ernst. Een API-aanroep naar een derde partij die faalt, door een timeout, een rate limit, of een tijdelijke storing aan hun kant, zou niet stilzwijgend de data moeten laten vallen die het probeerde te versturen. Gestructureerde retries met backoff, en een duidelijk escalatiepad (een gelogde fout die iemand kan zien en waarop kan worden gehandeld) wanneer retries zijn uitgeput, is het verschil tussen een integratie die bestand is tegen normale internethapering en een die stilzwijgend data verliest tijdens een slecht uur.

Foutzichtbaarheid doet er net zoveel toe als foutafhandeling. Een integratie die stilletjes faalt is erger dan een die luidruchtig faalt, omdat een luide storing wordt opgelost en een stille drift van data ophoopt die niemand opmerkt tot een klant of een afstemmingsrapport het weken later aan het licht brengt. Loggen wat werd verstuurd, wat terugkwam, en storingen ergens zichtbaar maken waar iemand daadwerkelijk kijkt, is onglamoureus werk dat zichzelf terugbetaalt de eerste keer dat er iets misgaat.

Het praktische startpunt voor elk integratieproject: breng elk systeem in kaart dat op dit moment data moet delen, kies een hub als je meer dan twee of drie betrokken systemen hebt (of van plan bent te hebben), en budgetteer echte tijd voor auth, rate limits en foutafhandeling in plaats van alleen de datamapping. Integratiewerk zo gedaan is jaren later nog te onderhouden. Integratiewerk gedaan als een reeks losse punt-tot-punt-verbindingen wordt de kluwen die niemand wil aanraken.