Wat is een API-koppeling?

Wat is het verschil tussen een API en een API-koppeling?

Een API is een voorziening van één systeem: een gedocumenteerde ingang waarlangs andere software gegevens kan opvragen of wegschrijven. Die ingang bestaat, of iemand er nu gebruik van maakt of niet. Een API-koppeling is het stuk software dat je daar zelf op bouwt: de verbinding tussen twee concrete systemen, met de afspraken over welke gegevens er heen en weer gaan.

Dat onderscheid is meer dan woordenspel. Dat een pakket "een API heeft" zegt niets over wat er mogelijk is. Het gaat om welke gegevens de API vrijgeeft, hoe vaak je die mag opvragen en of je ook mag wegschrijven. Die antwoorden bepalen hoeveel werk een koppeling wordt.

Hoe werkt een API-koppeling?

In de basis stelt het ene systeem een vraag en geeft het andere antwoord. Een webshop vraagt bijvoorbeeld: wat is de actuele voorraad van artikel 12345? Het ERP antwoordt met een getal. Bij het wegschrijven gaat het andersom: de webshop stuurt een nieuwe order, het ERP bevestigt dat die is aangemaakt en geeft een ordernummer terug.

Om dat veilig te laten verlopen moet elke aanvraag zich identificeren, meestal met een sleutel of een token. Verder spreken beide systemen hetzelfde formaat af, zodat een datum of een bedrag aan beide kanten hetzelfde betekent. Over de technische varianten daarvan, zoals REST en GraphQL, lees je meer in het artikel over middleware, API's en webhooks.

Eenrichtingsverkeer of twee kanten op?

Een koppeling kan gegevens één kant op sturen of beide kanten op. Eenrichtingsverkeer is eenvoudiger en voorspelbaarder: één systeem is de bron, het andere volgt. Tweerichtingsverkeer is krachtiger, maar vraagt een expliciete afspraak over wat er gebeurt als beide kanten hetzelfde veld hebben gewijzigd. Zonder die afspraak overschrijft de laatste wijziging stilletjes de eerste.

Daarnaast bepaal je de frequentie. Realtime betekent dat de koppeling reageert op het moment dat er iets gebeurt. Periodiek betekent dat er elk kwartier of elke nacht een batch wordt verwerkt. Realtime is niet automatisch beter: voor een voorraadstand telt elke minuut, voor een grootboekexport zelden.

API-koppeling, webhook of middleware?

Bij een API-koppeling vraagt het ene systeem actief om gegevens. Bij een webhook is het omgekeerd: het bronsysteem meldt uit zichzelf dat er iets is gebeurd, zodat de ontvanger niet hoeft te blijven vragen. Beide zijn verbindingen tussen twee systemen.

Zodra er meer systemen bij komen, wordt het aantal losse verbindingen het probleem. Dan komt er een laag tussen die de regie voert over wat waarheen gaat, middleware. Een API-koppeling verbindt dus twee systemen, middleware organiseert het verkeer tussen meerdere.

Wat heb je nodig voordat je een koppeling laat bouwen?

Vier dingen bepalen of een koppeling soepel verloopt. Ten eerste documentatie van de API: zonder beschrijving van de beschikbare gegevens en velden begint elk traject met uitzoekwerk. Ten tweede toegang tot een testomgeving, zodat je niet in de productieadministratie hoeft te oefenen. Ten derde duidelijkheid over limieten: veel leveranciers begrenzen het aantal aanvragen per minuut, en dat bepaalt of realtime haalbaar is. Ten vierde de licentievoorwaarden, want niet elk pakket geeft API-toegang binnen het abonnement dat je hebt.

Controleer dit voordat de scope vastligt. Een koppeling die technisch eenvoudig is kan alsnog stranden op een leverancier die geen schrijfrechten geeft. Voor een koppeling met een ERP-pakket staan de aandachtspunten uitgewerkt op de pagina over de ERP-koppeling.

Kort samengevat.

Een API-koppeling is de verbinding die je bouwt tussen twee systemen via de API die een van beide aanbiedt. Je bepaalt daarbij de richting, de frequentie en welk systeem leidend is bij tegenstrijdige gegevens. Een webhook draait de richting om en laat het bronsysteem zelf melden; middleware komt in beeld zodra meerdere systemen gegevens delen. Wat het meeste bepaalt of een koppeling lukt, is niet de techniek maar wat de leverancier van het andere systeem toestaat.