API-ontwikkeling en integraties: wat merken steeds fout doen bij het koppelen van systemen

Ieder nieuw systeem dat een merk toevoegt, maakt de vraag groter: hoe laat je dit praten met wat er al staat? CRM, CMS, betalingsprovider, loyaliteitsplatform, marketingautomatisering. Op een bepaald moment staan er tien systemen en zijn er twintig punt-tot-punt koppelingen die ze bij elkaar houden. Dan gaat er iets stuk en weet niemand meer waar.

Bij Livewall bouwen we webapplicaties en digitale platforms waarbij integraties geen bijzaak zijn, maar onderdeel van het ontwerp. En we zien hetzelfde patroon bij bijna elk project dat met legacy-koppelingen begint: de techniek is niet het probleem. De architectuur is het probleem.

De meest gemaakte fout: punt-tot-punt koppelen

Een merk integreert zijn CRM met zijn e-mailplatform. Direct, snel, opgelost. Dan komt er een loyaliteitsplatform bij, dus dat koppelen ze ook aan het CRM. Dan een app. Dan een dataplatform. Voor je het weet is elk systeem rechtstreeks verbonden met elk ander systeem en is de hele infrastructuur een kluwen van afhankelijkheden.

Dit is de punt-tot-punt-val. Elke koppeling ziet er op zichzelf logisch uit. Samen vormen ze een onderhoudsnachtmerrie. Eén API-wijziging bij de leverancier cascade-doorheen het hele landschap. Niemand durft meer iets te veranderen.

De oplossing is niet ingewikkeld: bouw een centrale integratielaag, of gebruik een API-gateway, die als enkel contactpunt dient voor externe systemen. Systemen praten met de gateway, niet met elkaar.

Geen versiebeheer op je API's

De tweede fout is het ontbreken van versioning. Teams bouwen een API, die werkt, en ze gaan door. Dan wil een ander team iets aanpassen. De endpoint verandert. Alles wat daaraan hangt, breekt.

Goed API-ontwerp gaat ervan uit dat dingen veranderen. Versioning is geen administratieve last, het is een belofte aan de systemen die van jouw API afhankelijk zijn. /v1/orders blijft werken, ook als /v2/orders een ander dataformaat retourneert. Consumers kiezen hun moment van migreren.

We zien dit het vaakst bij interne API's die ooit als tijdelijke oplossing zijn gebouwd. Geen documentatie, geen versioning, geen contract. En dan is het systeem zes jaar later nog altijd in productie en raakt niemand het meer aan uit angst.

Foutafhandeling als bijzaak

De derde fout is dat error handling achteraf wordt bedacht. Een API-aanroep mislukt. Wat gebeurt er? Als het antwoord alleen bestaat uit een stille time-out of een generieke 500-error, weet de ontvangende kant niets. Was het een tijdelijk probleem? Een datavalidatiefout? Een autorisatieprobleem?

Goede API's hebben expliciete foutcodes met betekenis. Ze onderscheiden 4xx-fouten (iets aan jouw kant) van 5xx-fouten (iets aan onze kant). Ze retourneren leesbare foutberichten die developers iets vertellen. En ze loggen aan beide kanten.

Retry-logica hoort ook bij het ontwerp, niet bij de implementatie achteraf. Weet je welke operaties idempotent zijn? Kun je dezelfde aanroep twee keer sturen zonder dubbele betalingen of dubbele records te maken? Als het antwoord 'weet ik niet' is, is er werk aan de winkel.

Authenticatie als nagedachte

API-beveiliging is het vierde gebied waar het misgaat. OAuth 2.0, API-sleutels, JWT-tokens: de keuze hangt af van de context. Maar wat we regelmatig zien is dat authenticatie wordt toegevoegd nadat de API al gebouwd is, waardoor de implementatie niet past bij het ontwerp.

Een API die intern wordt gebruikt heeft andere beveiligingseisen dan een API die externe partners of consumenten-apps bedient. Service-to-service communicatie werkt anders dan gebruikersauthenticatie. Scopes en rechten moeten from the start worden nagedacht, niet als een laagje vernis op een werkend systeem.

Rate limiting hoort hier ook bij. Zonder rate limiting is je API kwetsbaar voor misbruik en voor de eerlijke gebruiker die per ongeluk een loop schrijft die duizend aanroepen per seconde maakt.

Wat goede API-architectuur er anders uitziet

Goede API's hebben een enkel doel. Ze doen één ding goed en geven dat terug in een consistent formaat. Geen endpoints die tien verschillende operaties uitvoeren afhankelijk van de queryparameters. Geen response-objecten die groeien totdat niemand meer weet welke velden altijd aanwezig zijn.

Goede API's hebben een duidelijk contract. OpenAPI of een vergelijkbaar schema dat beschrijft wat elke endpoint accepteert, retourneert en hoe fouten eruitzien. Niet als documentatie achteraf, maar als het startpunt van de implementatie. Contract-first development voorkomt verrassingen aan beide kanten.

En goede API's groeien beheerst. Bij de KLM Scalable Growth-aanpak was schaalbaarheid over 50+ markten alleen mogelijk omdat het onderliggende systeem was gebouwd op schone integraties met duidelijke verantwoordelijkheden. Wanneer een nieuwe markt werd toegevoegd, volgde de integratie een patroon dat al werkte. Er was geen handmatige interventie per markt nodig.

Integraties stapelen zich op

Het echte probleem met slechte API-architectuur is dat het samengesteld is. Eén slecht geïntegreerd systeem is beheersbaar. Vijf ervan zorgen voor exponentieel meer risico en onderhoudslast.

Elke integratie die je toevoegt zonder duidelijk contract, zonder error handling, zonder versioning, is een investering in toekomstige problemen. Drie jaar later staan er tien van die koppelingen en kost elke platformmigratie twee keer zoveel als nodig, omdat niemand precies weet wat waar afhankelijk van is.

We hanteren bij Livewall een simpele vuistregel: als je een integratie niet kunt beschrijven in één zin ("systeem A stuurt gebruikersdata naar systeem B via de orders-API wanneer een aankoop is bevestigd"), dan is de scope waarschijnlijk te breed of de verantwoordelijkheidsverdeling onduidelijk.

De vraag die je moet stellen vóórdat je gaat bouwen is niet "hoe koppel ik dit", maar "wat is de minimale, meest stabiele verbinding die dit doel bereikt en over drie jaar nog te begrijpen is".