Wat is een API-koppeling?

Deze pagina legt de begrippen uit en laat zien waar het in de praktijk misgaat. Wilt u weten wat het kost om er een te laten bouwen, dan staat dat op de pagina over een API-koppeling laten maken.

Wat is een API en hoe werkt het?

API staat voor application programming interface. Dat is de ingang van een pakket voor andere software. Een mens gebruikt een scherm met knoppen. Een ander programma gebruikt de API.

Zo’n ingang werkt met verzoeken en antwoorden. Uw webshop stuurt een verzoek: geef mij alle bestellingen van vandaag. De API antwoordt met een lijst in een vaste vorm, meestal JSON. Dat is tekst die een programma kan lezen zonder te raden.

Het woord koppeling slaat op wat u eromheen bouwt. De API is de deur. De koppeling is wie er wanneer doorheen loopt, met welke gegevens en wat er gebeurt als de deur op slot zit.

De begrippen die u tegenkomt in een offerte

Vraagt u een offerte op voor een koppeling, dan staan deze woorden erin. Ze zijn geen jargon om indruk te maken. Ze bepalen wat het werk is.

Begrip

Wat het betekent

Endpoint

Eén specifiek adres in de API, bijvoorbeeld het adres voor facturen

Authenticatie

Hoe het andere pakket weet dat u het bent, meestal met een sleutel of een token

Rate limit

Hoeveel verzoeken u per minuut mag doen voordat het pakket u tijdelijk weigert. Bij Exact Online is dat 60 per minuut per administratie (opent in een nieuw tabblad)

Polling

Zelf periodiek vragen of er iets nieuws is

Webhook

Het andere pakket meldt zichzelf zodra er iets gebeurt

Idempotentie

Dezelfde opdracht twee keer sturen mag geen dubbele factuur opleveren

Die laatste twee zijn de dure. Een koppeling die polt terwijl er een webhook beschikbaar is, doet veel meer werk dan nodig. En een koppeling zonder idempotentie maakt bij een storing dubbele regels in uw boekhouding.

Polling of webhook: het verschil dat u merkt

Bij polling kijkt uw koppeling elke paar minuten of er iets nieuws is. Simpel te bouwen. Het kost alleen veel verzoeken en er zit altijd vertraging tussen.

Bij een webhook zegt het andere pakket het zelf zodra er iets gebeurt. Sneller en zuiniger. Alleen moet u dan wel een adres hebben dat altijd bereikbaar is. En u moet vastleggen wat er gebeurt als dat bericht niet aankomt.

Welke van de twee kan, verschilt per pakket. Kan het er maar één, dan is dat geen keuze maar een gegeven. Het is meteen de eerste vraag die u aan een bouwer stelt.

Wat een API-koppeling niet is

Een export naar Excel is geen koppeling. Het lijkt erop, want er gaan gegevens van A naar B. Het verschil is dat iemand op een knop moet drukken en dat er niets meldt als het misgaat.

Een import van een CSV-bestand op een vast tijdstip is een tussenvorm. Dat kan een prima oplossing zijn als een pakket geen API heeft. Noem het dan ook zo en niet een koppeling, want de verwachtingen zijn anders.

Middleware is weer iets anders. Dat is software die tussen meerdere systemen in staat en berichten vertaalt en doorstuurt. Bij twee pakketten heeft u dat vrijwel nooit nodig. Vanaf drie systemen wel.

Waar het in de praktijk misgaat

Het bouwen van een koppeling is zelden het lastige deel. Het lastige deel is alles wat daarna kan gebeuren.

Er komt geen melding als hij stopt. Dit is de duurste fout en hij komt het vaakst voor. Een koppeling die stil stopt, merkt u pas als een klant belt over een factuur die nooit is aangekomen. Elke koppeling hoort te controleren of de andere kant heeft bevestigd. Blijft die bevestiging uit, dan hoort er bericht uit te gaan.

Beide systemen beweren iets anders. U wijzigt een adres in twee pakketten. Welke wint? Zonder afspraak vooraf wint toevallig het laatste bericht. Leg vast welk systeem de baas is over welk gegeven.

De sleutel verloopt. Veel API’s werken met een token dat na een tijd vervalt. Wie dat niet automatisch vernieuwt, heeft vroeg of laat een koppeling die zwijgt.

Het andere pakket verandert. Leveranciers wijzigen hun API. Een goede koppeling faalt dan zichtbaar en niet stilletjes.

Wat te doen als een pakket geen API heeft

Een pakket zonder API komt vaker voor dan u denkt, vooral bij oudere software voor één specifieke branche. Er zijn dan drie wegen.

De eerste is een export op een vast tijdstip die automatisch wordt opgehaald en ingelezen. Minder elegant en het werkt prima, mits er een controle bij zit die telt of alles is aangekomen.

De tweede is de leverancier vragen. Soms bestaat er wel een API die niet in de folder staat.

De derde is het scherm nabootsen. Dat werkt en het breekt bij elke schermwijziging. Doe dit alleen als de andere twee dicht zitten en weet dat het onderhoud vraagt.

Vijf vragen aan wie uw koppeling gaat bouwen

Deze vragen kosten u vijf minuten en ze verschillen een goede offerte van een goedkope.

1. Heeft mijn pakket een API? Kunt u dat laten zien voordat u een prijs noemt?
2. Wordt het polling of een webhook? En waarom die keuze?
3. Wat gebeurt er als een bericht niet aankomt? Wie krijgt daar bericht van?
4. Welk systeem is de baas als beide iets anders beweren?
5. Van wie is de code als de koppeling klaar is?

Die laatste vraag stelt bijna niemand. Een koppeling die van de bouwer blijft, maakt u afhankelijk van iemand die u niet meer kunt missen.

Wat een API-koppeling kost

Voor een koppeling tussen twee pakketten met een werkende API ligt dat tussen € 1.450 en € 3.450 exclusief btw. Gaat het om meer dan twee systemen, dan loopt dat op tot € 5.450 tot € 12.500.

Wat de prijs bepaalt is zelden het aantal velden. Het zijn de uitzonderingen: wat er moet gebeuren bij een storing, hoe vaak er gesynchroniseerd wordt en of er historie moet worden meegenomen.

Over Achter de Schermen

Achter de Schermen is de eenmanszaak van Stefan Colin in Zwaag, West-Friesland. Ik bouw maatwerk software en koppel pakketten die elkaar niet kennen. Ook zoek ik uit waarom Google en AI-antwoorden een site overslaan en wat eraan te doen is.

Wilt u weten of een koppeling in uw geval kan, stuur dan de namen van de twee pakketten en wat er nu met de hand gebeurt.

Veelgestelde vragen