Webdevelopment & Webapps

API-koppelingen: hoe systemen met elkaar communiceren

Een API-koppeling is een verbinding waarlangs twee softwaresystemen automatisch gegevens uitwisselen via een API, een afgesproken set regels die bepaalt wat het ene systeem aan het andere mag vragen en in welke vorm het antwoord komt. Zo belandt een bestelling uit een webshop in de boekhouding zonder dat iemand ze overtypt.

In het kort

Wat is een API-koppeling? Het korte antwoord

API staat voor application programming interface. Het is het loket van een softwaresysteem: daar staat beschreven welke vragen je mag stellen, hoe je ze stelt en wat je terugkrijgt. Mensen gebruiken de schermen van een programma, andere programma’s gebruiken de API.

Een API-koppeling, ook API-integratie genoemd, is de code die twee van die loketten met elkaar verbindt. Ze haalt gegevens op bij het ene systeem, zet ze om naar wat het andere verwacht en levert ze daar af. Dat gebeurt op vaste tijdstippen, of meteen wanneer er iets verandert.

Het moeilijke deel is zelden de verbinding zelf. Het zit in de vragen eromheen: welke gegevens horen bij elkaar, welk systeem heeft gelijk bij een verschil, en wat gebeurt er wanneer een van de twee even niet bereikbaar is.

API koppeling – een webshop die via een API gegevens doorgeeft aan de boekhouding

De basis

Hoe werkt een API? Request en response

De meeste API’s op het web werken met HTTP, hetzelfde protocol waarmee een browser een pagina opvraagt. Het ene systeem stuurt een vraag, de request. Het andere stuurt een antwoord terug, de response.

Een request bestaat uit een adres, een werkwoord dat zegt wat je wilt doen, en soms gegevens. De response bevat een statuscode en meestal gegevens in JSON, een tekstformaat dat mensen en programma’s allebei kunnen lezen.

De request: één bestelling opvragen (fictief voorbeeld)
GET https://api.example.com/bestellingen/1042
Authorization: Bearer <geheime-sleutel>
Accept: application/json
De response: statuscode en gegevens
200 OK
Content-Type: application/json

{
  "id": 1042,
  "status": "betaald",
  "klant_id": 318,
  "aantal_regels": 3
}

Het werkwoord bepaalt de actie: GET vraagt gegevens op, POST maakt iets aan, PUT of PATCH wijzigt en DELETE verwijdert. De statuscode zegt hoe het afliep. Begint ze met een 2, dan is het gelukt. Een 4 wijst op een fout in de vraag, een 5 op een fout bij de server.

Welke adressen, velden en codes een API gebruikt, staat in haar documentatie. De algemene regels van HTTP zijn beschreven bij MDN.

Onderdelen

Authenticatie, webhooks en datamapping

Een verbinding leggen is het begin. Een koppeling die blijft werken, bestaat uit een paar vaste onderdelen. Wie ze kent, leest een offerte of een technisch voorstel met meer inzicht.

01

Authenticatie

De API moet weten wie de vraag stelt. De eenvoudigste vorm is een API-sleutel: een geheime code die bij elke request meegaat. Bij OAuth geeft een gebruiker een toepassing toegang tot zijn account zonder zijn wachtwoord te delen. De toepassing krijgt een token dat beperkt is in tijd en in wat het mag.

02

Webhooks

Een gewone API antwoordt alleen wanneer je iets vraagt. Een webhook draait dat om: het andere systeem stuurt zelf een bericht naar een adres van jou zodra er iets gebeurt, zoals een betaling of een nieuwe bestelling. Zo hoef je niet telkens te gaan kijken of er iets veranderd is.

03

Datamapping

Twee systemen noemen hetzelfde zelden op dezelfde manier. Wat hier ‘klantnummer’ heet, is daar een ‘relatiecode’. Datums, landen, btw-tarieven en eenheden hebben elk hun eigen notatie. Datamapping legt per veld vast wat waarmee overeenkomt en hoe het omgezet wordt.

04

Richting en bron

Gaan de gegevens één kant op, of in beide richtingen? En welk systeem heeft gelijk wanneer hetzelfde gegeven op twee plekken anders is? Wie dat niet vooraf vastlegt, krijgt wijzigingen die elkaar overschrijven.

Betrouwbaarheid

Fouten en retries: wat als het misloopt?

Elke koppeling valt vroeg of laat eens uit: een dienst is traag, een sleutel is verlopen, een veld is leeg. Een goede koppeling gaat daar niet van stuk. Ze vangt de fout op en laat weten dat er iets aan de hand is. Die afhandeling draait op de server. Hoe dat in JavaScript gebeurt, lees je in Node.js als backend.

  • Time-outs Niet eindeloos wachten op een antwoord dat niet komt, zodat de rest van de toepassing blijft werken.
  • Retries Een mislukte request opnieuw proberen, met telkens een langere pauze ertussen en een maximum aantal pogingen.
  • Geen dubbele verwerking Een bericht dat twee keer aankomt, mag maar één keer een bestelling of betaling opleveren. Dat heet idempotentie.
  • Limieten respecteren Veel API’s beperken hoeveel requests je per tijdseenheid mag sturen. De koppeling houdt daar rekening mee.
  • Een wachtrij Wat nu niet afgeleverd kan worden, wordt bewaard en later opnieuw aangeboden in plaats van te verdwijnen.
  • Logboek en melding Elke uitwisseling wordt bijgehouden, en iemand krijgt bericht wanneer een fout zich niet vanzelf oplost.

Beveiliging

Hoe beveilig je een API-koppeling?

Een koppeling is een deur tussen twee systemen. Ze geeft toegang tot gegevens van klanten, bestellingen of betalingen, en verdient dus dezelfde zorg als een login.

  • Versleutelde verbinding Alle verkeer loopt over HTTPS, zodat niemand onderweg kan meelezen.
  • Sleutels buiten de code API-sleutels en tokens staan in een beveiligde configuratie, nooit in de broncode of in een e-mail.
  • Zo weinig rechten als nodig Een sleutel die alleen bestellingen moet lezen, mag geen klanten kunnen verwijderen.
  • Webhooks controleren Een binnenkomend bericht wordt pas vertrouwd nadat de handtekening van de afzender nagekeken is.
  • Invoer valideren Ook gegevens uit een ander systeem worden gecontroleerd voor ze in je eigen database terechtkomen.
  • Alleen wat nodig is Persoonsgegevens die het andere systeem niet nodig heeft, stuur je niet mee.

Voorbeelden

Welke systemen worden vaak gekoppeld?

In een KMO draaien al snel meerdere pakketten naast elkaar, elk met een eigen stuk van dezelfde gegevens. Deze categorieën komen geregeld terug. Veel van die pakketten zijn SaaS-platformen. Wat dat inhoudt, lees je in Wat is een SaaS-platform?

Voorbeelden van API-koppelingen per soort systeem
Soort systeemWat er uitgewisseld wordtAandachtspunt
CRMContacten, bedrijven en aanvragen uit een website of webapplicatieDubbele contacten vermijden: waaraan herken je dezelfde klant?
ERP of boekhoudingKlanten, artikelen, bestellingen en facturenBtw, nummering en afrondingen moeten exact overeenkomen.
BetalingenEen betaling starten en de status ervan ontvangenDe status komt meestal via een webhook, en die kan vertraagd of dubbel aankomen.
ProductfeedsProducten, prijzen en voorraad naar vergelijkers, marktplaatsen of advertentieplatformenElk kanaal stelt eigen eisen aan velden en formaten.

De tabel noemt bewust geen pakketten. Wat mogelijk is, hangt af van de API die jouw leverancier aanbiedt en van hoe goed die gedocumenteerd is. Ook AI-systemen worden via een API aangesproken: dat staat in het artikel over AI-integraties.

De keuze

Wanneer is een API-koppeling op maat nodig?

Niet elke koppeling moet gebouwd worden. Veel pakketten hebben ingebouwde koppelingen, en automatiseringsplatformen verbinden gangbare software zonder code. Begin daar, en kijk pas naar maatwerk wanneer dat niet volstaat.

Een bestaande koppeling volstaat wanneer

  • de leverancier zelf een koppeling met het andere pakket aanbiedt
  • de gegevens zonder omzetting overgenomen kunnen worden
  • het om kleine aantallen gaat
  • een fout weinig gevolgen heeft en snel opgemerkt wordt

Maatwerk wordt logisch wanneer

  • er geen kant-en-klare koppeling tussen de twee systemen bestaat
  • gegevens omgezet, samengevoegd of gecontroleerd moeten worden
  • eigen bedrijfsregels bepalen wat wanneer doorgestuurd wordt
  • meer dan twee systemen dezelfde gegevens delen
  • een fout geld of klanten kost en dus opgevangen moet worden

Een koppeling op maat is een klein stuk software met eigen onderhoud: API’s veranderen, en de koppeling moet mee. Hoe ik zulke projecten als dienst aanpak, lees je op de pagina over integraties en API-koppelingen. De bredere afweging tussen standaard en maatwerk staat in Maatwerk software of standaardpakket?

FAQ

Veelgestelde vragen over API-koppelingen

Een API is het aanspreekpunt van één systeem: de beschrijving van wat je kunt opvragen en doorsturen. Een API-koppeling is de verbinding die met dat aanspreekpunt werkt en gegevens tussen twee systemen laat stromen. De API bestaat dus al, de koppeling moet nog gebouwd of ingesteld worden.

REST is een veelgebruikte manier om een web-API op te bouwen. Elk soort gegeven krijgt een eigen adres, zoals klanten of bestellingen, en je gebruikt vaste werkwoorden om ze op te vragen, aan te maken, te wijzigen of te verwijderen. De gegevens komen meestal terug als JSON.

Bij een API vraag jij iets op wanneer jij dat wilt. Bij een webhook stuurt het andere systeem zelf een bericht zodra er iets gebeurt, bijvoorbeeld een nieuwe betaling. Veel koppelingen gebruiken allebei: de webhook meldt dat er iets veranderd is, de API haalt daarna de details op.

Nee. Veel online software heeft er een, maar niet elk pakket, en niet elke API geeft toegang tot alle gegevens. Soms zit de API alleen in een duurdere formule. Vraag het na bij de leverancier en bekijk de documentatie voor je een pakket kiest waarmee je later wilt koppelen.

Dat hangt af van het aantal systemen, de kwaliteit van hun documentatie, de hoeveelheid gegevens en wat er moet gebeuren wanneer iets misloopt. Een vast bedrag bestaat daardoor niet. Bij MadeByDries geldt voor maatwerk prijs op aanvraag, na een eerste afbakening.

Meer over dit onderwerp

Verder lezen

De dienst bij dit onderwerp

Integraties en API-koppelingen als dienst

Moeten je systemen gegevens uitwisselen en bestaat er geen kant-en-klare koppeling? Op de dienstpagina lees je welke toepassingen en integraties ik op maat bouw en hoe een project verloopt.

Dries Nijs, Organic Web Specialist en auteur van dit artikel

Over de auteur

Dries Nijs, Organic Web Specialist

Ik ben Dries Nijs, developer uit Maasmechelen. Ik bouw sinds de jaren 90 voor het web en ontwikkel vandaag webapplicaties in React, Next.js en Node.js, naast websites in WordPress. MadeByDries is het persoonlijke merk waaronder ik werk.

Moeten twee systemen met elkaar praten?

Vertel me welke pakketten je gebruikt en welke gegevens vandaag overgetypt worden. Dan bekijken we of een bestaande koppeling volstaat of maatwerk nodig is.

Bespreek je project

Vertel me wat je wilt bouwen of verbeteren

Je hoeft nog geen technische briefing te hebben. Vertel me waar je nu staat en wat je wilt bereiken, dan denk ik mee over de juiste aanpak.

Kies minstens één onderwerp. Meer dan één mag ook.

Ik gebruik je gegevens alleen om op je aanvraag te reageren.

Liever meteen mailen?

Locatie
Maasmechelen, België