Een API-koppeling is een vaste verbinding tussen twee softwaresystemen, waarmee ze zonder tussenkomst van een mens gegevens bij elkaar opvragen en naar elkaar toe sturen. Je webshop haalt de voorraad op uit het magazijnsysteem, je boekhouding ontvangt een order zodra die binnenkomt, en niemand hoeft iets over te typen.
Het woord valt vaak in een gesprek over software zonder dat iemand uitlegt wat er nu precies gebeurt. Hieronder staat waar de afkorting voor staat, hoe zo’n verbinding werkt, welke soorten er zijn, hoe het met de beveiliging zit en waar een koppeling in de praktijk op stukloopt.
Waar staat API voor?
API staat voor Application Programming Interface. Je kunt het lezen als programmeerkoppeling: de plek waar een systeem aangeeft welke vragen je mag stellen en in welke vorm het antwoord terugkomt.
Zo’n interface bestaat uit een lijst adressen die je kunt aanroepen, en per adres een afspraak over wat je moet meesturen en wat je terugkrijgt. Exact Online heeft er een voor facturen en relaties, Mollie een voor betalingen, Hexon een voor voertuigdata. De leverancier van het systeem bepaalt zelf hoever die lijst reikt.
De woorden API en API-koppeling worden door elkaar gebruikt, terwijl ze iets anders aanduiden. De API is wat de leverancier aanbiedt. De koppeling is wat jij ermee bouwt. Daardoor kan een pakket wel een API hebben terwijl de koppeling die jij nodig hebt nog moet worden gemaakt.
Hoe werkt een API-koppeling?
Een koppeling doet steeds hetzelfde. Hij stuurt een verzoek naar een adres bij het andere systeem, laat zien wie hij is, en krijgt een antwoord terug in een vaste vorm. Dat antwoord is meestal JSON, een tekstformaat dat een programma direct kan uitlezen.
Er zitten vier onderdelen aan.
Het endpoint. Het adres dat je aanroept, met daarachter wat je wilt: alle klanten opvragen, één order aanmaken, de voorraad van een artikel ophalen. Elk soort verzoek heeft zijn eigen adres.
De authenticatie. Vrijwel elke API wil weten wie er aanklopt. Dat gaat met een sleutel die je meestuurt, of met een token dat je eerst ophaalt en dat na een tijdje verloopt. Die laatste vorm heet OAuth en is inmiddels het meest gebruikelijk.
De gegevens zelf. Het klantnummer in systeem A heet anders in systeem B, en een datum wordt door beide anders opgeschreven. Dat vertaalwerk tussen velden is vaak het grootste deel van de bouwtijd. Wat er aan de ontvangende kant mee gebeurt, hangt af van hoe de database is ingericht.
Het moment. Ophalen op afroep betekent dat de koppeling elk kwartier of elk uur vraagt of er iets nieuws is. Bij een webhook werkt het omgekeerd en stuurt het andere systeem jou een bericht zodra er iets verandert. Webhooks zijn sneller en belasten beide systemen minder.
De eerste geslaagde aanroep is meestal binnen een dag geregeld. Het werk zit in wat daarna komt. Wat gebeurt er als het andere systeem er even uit ligt? Wat als een verplicht veld leeg blijkt, of als dezelfde order twee keer binnenkomt? Een koppeling zonder antwoord op die vragen valt na een paar weken stil zonder dat iemand het merkt.
Welke soorten API-koppelingen zijn er?
De meeste koppelingen die je vandaag tegenkomt zijn REST-koppelingen. Daarnaast bestaan SOAP, GraphQL en webhooks, en bij oudere systemen kom je nog uitwisseling via bestanden tegen.
REST. De gangbare vorm. Werkt over https, antwoordt in JSON en is vanuit elke programmeertaal aan te spreken. Als een leverancier het over “de API” heeft, gaat het hierover.
SOAP. Ouder, met XML en een strak vastgelegd contract. Je komt het tegen bij banken, verzekeraars en overheidssystemen. Het werkt goed en het kost meer werk om op te zetten.
GraphQL. Hier vraag je in één verzoek precies de velden op die je nodig hebt. Dat scheelt als een REST-API je dwingt tot vijf aanroepen om één scherm te vullen.
Webhooks. Het andere systeem meldt zich bij jou zodra er iets gebeurt, bijvoorbeeld bij een geslaagde betaling. Vaak gebruik je een webhook en een REST-API naast elkaar, waarbij de webhook het signaal geeft en de API de details ophaalt. Daarmee wordt de koppeling realtime: een wijziging staat binnen een seconde in het andere systeem, in plaats van bij de volgende ronde van de koppeling. Voor voorraad, betalingen en orderstatus is dat het verschil tussen bruikbaar en te laat.
Bestandsuitwisseling. Een CSV of XML op een FTP-server, meestal één keer per nacht. Formeel is dit geen API. Bij systemen die geen API hebben is het soms de enige weg naar binnen, met als nadeel dat je gegevens altijd een halve dag oud zijn.
Welke soort het wordt, bepaalt de leverancier van het andere systeem. Daar kies je zelf weinig in. Wat je wel kiest, is of je een bestaande standaardkoppeling gebruikt of een API-koppeling laten maken die op jouw proces past. Bestaat er een kant-en-klare koppeling met precies jouw pakket en doet die wat je nodig hebt, dan is dat de goedkoopste route.
Wat is het verschil tussen een API-koppeling en een OCI-koppeling?
Een OCI-koppeling is een koppeling uit de inkoopwereld, waarmee een inkoopsysteem de webshop van een leverancier binnen het eigen scherm opent en de gevulde winkelwagen terugstuurt als bestelaanvraag. OCI staat voor Open Catalog Interface, een standaard die uit SAP komt.
Het verschil zit in wie de handeling doet. Bij OCI stapt de inkoper zelf de catalogus van de leverancier binnen en komt terug met een mandje. Bij een API-koppeling wisselen de systemen onderling gegevens uit en ziet de gebruiker daar niets van. Bij OCI zit er dus een mens in het proces.
In de praktijk komen ze samen voor. Een groothandel met zakelijke klanten heeft OCI voor het bestelmoment en daarnaast API-koppelingen voor voorraad, prijsafspraken en orderstatus. Bij onze klant BD-Totaal hebben we een OCI-koppeling gerealiseerd en de API-documentatie geschreven. Inkopers komen daar vanuit hun eigen inkoopsysteem binnen, en de prijsafspraken en de voorraad die ze te zien krijgen komen live uit het back-officesysteem. Verwante standaarden in dezelfde hoek zijn cXML en Peppol voor facturen. Punchout is de Amerikaanse term voor hetzelfde principe als OCI.
Hoe veilig is een API-koppeling?
Een goed opgezette API-koppeling is veiliger dan het exportbestand dat hij vervangt, want er blijft geen bestand met klantgegevens op een bureaublad of in een mailbox achter. Hoe veilig hij is, hangt af van hoe de koppeling zich aanmeldt en welke rechten hij daarbij krijgt.
Versleuteld verkeer. Alles over https. Een API die ook over http bereikbaar is, geeft je sleutel in leesbare vorm mee over de lijn.
Zo weinig rechten als het werk toelaat. Een koppeling die alleen voorraad ophaalt, hoeft geen facturen te kunnen wijzigen. Veel API’s laten je per sleutel instellen wat die mag. Stel dat ook echt in, want de standaardinstelling is meestal volledige toegang.
IP-restrictie. Veel API’s laten je vastleggen vanaf welk IP-adres de koppeling mag verbinden. Belandt de sleutel dan alsnog ergens waar hij niet hoort, dan is hij buiten jouw server onbruikbaar. Vraag ernaar bij de leverancier, want het kan vaker dan je denkt en het staat vrijwel nooit standaard aan.
Vastleggen wat er gebeurt. Log welke aanroepen er zijn geweest en wat het antwoord was. Zonder die log kun je achteraf niet vaststellen welke gegevens er precies zijn uitgewisseld.
Persoonsgegevens. Gaan er persoonsgegevens over de koppeling, dan hoort daar een verwerkersovereenkomst bij en moet je weten waar de andere partij die gegevens opslaat. Binnen of buiten de EU maakt verschil.
Hoe we authenticatie, rechten en toegang dichtzetten staat bij beveiliging voor websites en applicaties.
Waar loopt een koppeling in de praktijk vast?
Bijna nooit op de techniek van de koppeling zelf. Vier dingen komen steeds terug.
De API kan minder dan de brochure suggereert. Een veld dat in de interface van het pakket gewoon zichtbaar is, blijkt soms niet via de API op te vragen. Dat merk je pas als je begint. Vraag daarom de documentatie op voordat er een begroting ligt.
Limieten op het aantal aanroepen. Veel API’s staan een beperkt aantal verzoeken per minuut toe. Bij tweehonderd artikelen valt dat niet op, bij twintigduizend loop je er de eerste dag tegenaan.
De gegevens sluiten niet op elkaar aan. Twee systemen die dezelfde klant anders spellen of een ander artikelnummer aanhouden, hebben iets nodig om die records aan elkaar te knopen. Bij het in gebruik nemen van een nieuwe koppeling trekken wij die gegevens eenmalig gelijk. Wat automatisch te matchen is syncen we, en wat overblijft koppelen we handmatig.
Wijzigingen aan de andere kant. Een leverancier die zijn API vernieuwt, geeft je een termijn om mee te gaan. Is er niemand die zulke berichten opvolgt, dan staat de koppeling op een ochtend stil. Daarom sluiten wij vaak een onderhoudscontract af.
Wat kost een API-koppeling?
De prijs hangt af van hoeveel systemen er meedoen, hoe bruikbaar de API van de tegenpartij is en of gegevens één of twee kanten op moeten. Wat een koppeling bij ons kost en wat de prijs precies bepaalt, staat op de pagina API-koppeling laten maken.
Een koppeling is zelden een los project. Vaak hoort hij bij iets groters, zoals een maatwerk webapplicatie of een klantportaal dat gegevens uit je bestaande systemen haalt. Een overzicht van de systemen en technieken waarmee we koppelen staat op een eigen pagina.
Veelgestelde vragen
Is een API-koppeling hetzelfde als een integratie?
Integratie is het bredere woord voor twee systemen laten samenwerken. Een API-koppeling is de manier waarop dat vandaag bijna altijd gebeurt. Wie het over een integratie heeft, bedoelt in de praktijk meestal een API-koppeling.
Kan een API-koppeling twee kanten op werken?
Ja, je kunt in één koppeling gegevens ophalen en wegschrijven, zolang de API van het andere systeem dat toelaat. Bij tweerichtingsverkeer moet je per veld afspreken welk systeem de baas is. Zonder die afspraak overschrijven de twee systemen elkaars wijzigingen.
Kan ik systemen koppelen met Zapier of Make in plaats van maatwerk?
Voor een paar eenvoudige stappen tussen twee bekende pakketten werkt dat goed en ben je snel klaar. Zodra er logica bij komt, er duizenden regels per maand door de koppeling gaan of gegevens omgezet moeten worden, loop je tegen de grenzen en de kosten van zo’n dienst aan. Vanaf dat punt is een eigen koppeling meestal goedkoper en beter te onderhouden.
Wat gebeurt er als het andere systeem offline is?
Wij zetten elke uitgaande API-aanroep op een queueserver. Lukt de aanroep niet omdat het andere systeem er even uit ligt, dan blijft de opdracht in de wachtrij staan en wordt hij later automatisch opnieuw uitgevoerd, zodat er geen gegevens verloren gaan. Zonder die queueserver verdwijnt de order of de wijziging die op dat moment onderweg was.
Twijfel je of jouw twee systemen aan elkaar te knopen zijn? Laat weten welke pakketten het zijn en wat er tussen zou moeten gaan, dan zeggen we of het kan en wat ervoor nodig is. Je kunt ons bereiken via contact.
