Wat is een API-koppeling in gewone taal

Wat is een API koppeling? In offertes staat het woord alsof iedereen het kent, en in gesprekken durft niemand door te vragen. Terwijl het idee erachter simpel is: een API is een vaste balie waar het ene systeem aan het andere iets kan vragen of doorgeven, in een formaat waar allebei de partijen zich aan houden.

Het beeld dat wij vaak gebruiken: een restaurant. U ziet de keuken niet en u mag er ook niet in. U geeft uw bestelling door aan de ober, in de vorm die op de kaart staat, en u krijgt terug wat u besteld heeft. De ober is de API. De keuken is het systeem waar u niets van hoeft te weten.

Wat er heen en weer gaat

Een verzoek aan een API bestaat uit drie dingen: een adres, een sleutel en een vraag. Het adres is een webadres van de andere partij. De sleutel bewijst dat u het bent, vergelijkbaar met een wachtwoord maar dan voor systemen. De vraag is wat u wilt weten of wilt doorgeven.

Wat er terugkomt is meestal een blokje gestructureerde tekst: naam, bedrag, status, datum, netjes in vakjes. Niet bedoeld voor mensen, wel makkelijk door software te lezen. Als u ooit een technisch scherm heeft gezien met veel accolades en aanhalingstekens, dan heeft u zo’n antwoord al eens langs zien komen.

Wat u er op uw site aan heeft

Concrete voorbeelden die op Nederlandse MKB-sites gewoon voorkomen:

• Betalingen. Uw webshop vraagt aan de betaaldienst of een bestelling betaald is, en zet de status op basis daarvan om.
• Verzending. Bij een nieuwe bestelling wordt automatisch een verzendlabel aangemaakt en het volgnummer teruggegeven.
• Boekhouding. Elke factuur uit uw shop belandt in uw boekhoudpakket zonder dat iemand overtypt, zoals beschreven bij het koppelen van uw webshop aan uw administratie.
• Nieuwsbrief. Wie zich aanmeldt op uw site, staat een minuut later in de juiste lijst.
• Voorraad. Uw kassasysteem geeft aantallen door, zodat uw shop niets verkoopt wat in de winkel al weg is.
• AI. Uw chatbot stuurt de vraag van een bezoeker naar het taalmodel en krijgt het antwoord terug. Precies hetzelfde principe.

Die laatste is het vermelden waard, omdat AI vaak als iets aparts wordt gepresenteerd. Technisch is het een gewone koppeling met een dienst die tekst teruggeeft in plaats van een pakketstatus.

Waarom koppelingen stukgaan

Een koppeling is geen apparaat dat u ophangt en vergeet. Het is een afspraak tussen twee partijen die allebei doorontwikkelen. Vijf oorzaken die we in de praktijk het vaakst tegenkomen:

1. De sleutel verloopt. Veel diensten laten sleutels na een jaar aflopen, of trekken ze in als er een medewerker vertrekt bij wie het account stond.
2. De andere kant verandert iets. Een veld heet anders, of een oudere versie van de balie wordt uitgezet. Meestal wordt dat maanden vooraf aangekondigd in een mail die niemand leest.
3. Een limiet wordt geraakt. Diensten staan een maximum aantal verzoeken per minuut toe. Bij een piek of een verkeerd ingestelde herhaling loopt u daartegenaan.
4. Een update aan uw kant. Een pluginupdate of een nieuwere PHP-versie kan de koppelingscode raken.
5. Een beveiligingsmaatregel blokkeert het verkeer. Firewalls houden geregeld legitieme verzoeken tegen omdat ze van een onbekend adres komen.

Wat al die gevallen gemeen hebben: het stopt stil. Er verschijnt geen rood kruis op uw website. De bestellingen blijven binnenkomen, alleen komen ze niet meer aan in uw boekhouding, en dat merkt u bij de kwartaalaangifte.

Wat een koppeling kost

Voorzichtig, want dit verschilt sterk. Een kant-en-klare plugin voor een gangbare dienst kost vaak enkele tientallen tot een paar honderd euro per jaar, plus wat instelwerk. Maatwerk tussen twee systemen die elkaar niet standaard kennen, loopt in de markt al snel van enkele honderden tot enkele duizenden euro’s, afhankelijk van hoeveel velden en uitzonderingen er zijn.

De post die vrijwel altijd wordt vergeten, is het onderhoud erna. Reken op periodieke controle, af en toe een aanpassing en een keer per paar jaar een grotere ingreep als een leverancier zijn systeem vernieuwt. Wie alleen de bouwkosten begroot, komt bedrogen uit.

Hoe u merkt dat het misgaat

Omdat zo’n verbinding stil uitvalt, moet u het zelf zichtbaar maken. Dat kan eenvoudiger dan bouwers soms doen voorkomen.

De goedkoopste methode is tellen. Staan er in uw shop twaalf bestellingen en in uw boekhouding negen facturen, dan weet u genoeg. Maak van die vergelijking een vaste gewoonte aan het begin van elke maand; het kost vijf minuten en het vindt problemen die geen enkel scherm meldt.

Daarnaast helpt een eenvoudige signalering. Veel koppelingen kunnen bij een mislukte poging een bericht sturen. Zet dat aan, maar stel het zo in dat u niet bij elke hik een mail krijgt, want een meldingenstroom die iedereen wegklikt is net zo blind als helemaal geen melding.

Let tot slot op het patroon in de tijd. Verbindingen vallen zelden om op een willekeurige dinsdag. Het gebeurt na een update, na een wachtwoordwijziging, of nadat een leverancier iets heeft aangekondigd. Zet die momenten in uw agenda als controlemoment, dan vindt u de storing binnen een dag in plaats van binnen een kwartaal.

Waar u op let bij het inrichten

Vier punten waar wij standaard naar kijken en die u in elk gesprek met een bouwer mag noemen.

Meldingen bij storing. Als een koppeling drie keer achter elkaar faalt, hoort er iemand een bericht te krijgen. Dit is de goedkoopste maatregel met het grootste effect.

Bewaren van wat er misging. Een logboek met de mislukte verzoeken, zodat herstel niet betekent dat u handmatig moet reconstrueren wat er ontbreekt.

Sleutels op de juiste plek. Niet in een pluginscherm dat elke beheerder kan openen, maar in het configuratiebestand van de site. Dat scheelt bij vertrekkende medewerkers een hoop gedoe.

Beperken wat de sleutel mag. Veel diensten laten u sleutels aanmaken met alleen leesrechten. Gebruik die waar dat kan; het beperkt de schade als er iets uitlekt. Hetzelfde denken past u toe als u de eigen API van WordPress afschermt.

Koppelingen zijn kortom geen eenmalig project maar een klein stukje techniek dat meeloopt in het gewone bijhouden van uw site. Wij nemen ze daarom mee in de maandelijkse controle, samen met de AI-onderdelen die er tegenwoordig bij horen; wat dat inhoudt, staat bij koppelingen en AI die met uw site meedraaien. Een koppeling die niemand controleert, is uiteindelijk een koppeling die niet werkt.