Wat is een API precies?

Een API is een afgesproken manier waarop twee systemen gegevens uitwisselen. Je kunt het zien als een loket met vaste formulieren: het ene systeem vraagt iets op of levert iets aan, en de API bepaalt in welke vorm dat moet en wat er terugkomt. Voor de gebruiker is er niets van te zien; het gebeurt tussen de systemen onderling. De meeste moderne software heeft een API, maar de kwaliteit en de documentatie ervan lopen sterk uiteen.

Wat als mijn systeem geen API heeft?

Dan zijn er omwegen, maar die zijn kwetsbaarder en duurder. Bestandsuitwisseling via een vaste map is een gangbaar alternatief: het ene systeem zet periodiek een bestand klaar en het andere haalt dat op. Ook rechtstreekse toegang tot de database komt voor, al is dat riskanter. In het uiterste geval wordt er geautomatiseerd door een scherm heen gewerkt, wat breekt zodra de leverancier iets wijzigt. Weeg bij een ouder pakket ook mee of vervanging op termijn goedkoper is.

Realtime of periodiek synchroniseren?

Dat hangt af van hoe vers de gegevens moeten zijn. Realtime betekent dat een wijziging meteen wordt doorgegeven, wat nodig is bij voorraad in een drukke webshop. Periodiek, bijvoorbeeld elk kwartier of elke nacht, is eenvoudiger, goedkoper en robuuster: als er iets misgaat, gebeurt dat in een afgebakend moment dat je kunt herhalen. Kies realtime alleen waar het echt nodig is, want het maakt storingzoeken en herstel aanzienlijk lastiger.

Wie is verantwoordelijk als de koppeling stopt met werken?

Meestal ligt de oorzaak bij een wijziging aan de andere kant: de leverancier van het CRM of het boekhoudpakket brengt een nieuwe versie uit en de koppeling sluit niet meer aan. Formeel is dat niemands fout, maar het probleem is wel van jou. Leg daarom vast wie de koppeling bewaakt, hoe snel er wordt gereageerd en of aanpassing aan wijzigingen van derden onder onderhoud valt of als meerwerk wordt gefactureerd.

Kan ik een kant en klare koppeling gebruiken?

Voor veelgebruikte combinaties bestaan bestaande koppelingen of tussenplatformen die het werk grotendeels doen. Die zijn aanzienlijk goedkoper dan maatwerk en worden door de leverancier onderhouden. De beperking is dat ze doen wat ze doen: wijkt jouw proces af, dan pas je of het proces aan of je bouwt alsnog maatwerk. Laat altijd eerst onderzoeken of er een bestaande oplossing is voordat je een koppeling laat bouwen.

Koppelingen en API’s | WebdesignVergelijker.nl

Q: Wat gebeurt er als het andere systeem uitvalt?

Dat is de belangrijkste vraag bij elke koppeling, en hij wordt te weinig gesteld. Een goed gebouwde koppeling bewaart wat er niet verstuurd kon worden en probeert het later opnieuw, in plaats van de gegevens te laten verdwijnen. Er hoort ook een melding te komen bij een aanhoudende storing, zodat iemand ingrijpt voordat er dagen aan bestellingen zijn blijven liggen. Vraag expliciet hoe dit is geregeld en wie de melding ontvangt.

Wat zijn koppelingen en API’s?

Een koppeling laat een website automatisch gegevens uitwisselen met een ander systeem. Een bestelling in de webshop verschijnt in het boekhoudpakket, de voorraad op de site komt uit het magazijnsysteem, een aanvraagformulier maakt meteen een record aan in het CRM. Zonder koppeling gebeurt datzelfde met de hand, met de vertraging en de tikfouten die daarbij horen.

De techniek daarachter is meestal een API: een afgesproken manier waarop twee systemen elkaar bevragen en gegevens aanleveren. Het ene systeem stelt een vraag in een vaste vorm, het andere antwoordt in een vaste vorm. Wat er tussen die twee gebeurt, ziet de gebruiker niet, maar het bepaalt wel of gegevens kloppen en of ze op tijd op de goede plek staan.

Koppelingen zijn berucht om het verschil tussen hoe eenvoudig ze klinken en hoeveel werk ze zijn. De gelukkige route, waarin alles werkt en alle gegevens compleet zijn, is doorgaans snel gebouwd. Het meeste werk zit in wat daarna komt: wat gebeurt er als het andere systeem er even niet is, als een veld leeg blijkt, als hetzelfde bericht twee keer binnenkomt, of als de leverancier zonder aankondiging iets wijzigt.

Wat valt er precies onder?

Een koppeling bouwen omvat het uitwisselen zelf, maar vooral het opvangen van alles wat er mis kan gaan.

Inventarisatie: uitzoeken welke systemen welke gegevens bezitten en welke kant het verkeer op moet.
Veldafbeelding: bepalen welk veld in het ene systeem hoort bij welk veld in het andere, inclusief afwijkende formaten en eenheden.
Richting en frequentie: eenrichtingsverkeer of beide kanten op, en of het realtime gebeurt of periodiek.
Authenticatie: veilig toegang regelen tussen de systemen, met sleutels die beheerd en vernieuwd moeten worden.
Foutafhandeling: bewaren en opnieuw proberen wat niet is aangekomen, zodat gegevens niet stilzwijgend verdwijnen.
Ontdubbeling: voorkomen dat een bericht dat twee keer binnenkomt ook twee keer wordt verwerkt.
Logging en bewaking: vastleggen wat er is uitgewisseld en melden zodra een koppeling langer stilstaat.
Documentatie: beschrijven hoe de koppeling werkt, zodat een andere partij hem later kan overnemen.

Hoe verloopt het bouwen van een koppeling?

Het uitzoekwerk vooraf bepaalt bij koppelingen vrijwel volledig hoe soepel de bouw verloopt.

Onderzoek naar de systemen. Er wordt vastgesteld welke API’s beschikbaar zijn, wat ze kunnen en hoe goed ze zijn gedocumenteerd. Bij oudere pakketten valt dit vaak tegen.
Gegevens in kaart brengen. Per veld wordt bepaald waar het vandaan komt, waar het heen gaat en wat er gebeurt als het ontbreekt of afwijkt.
Scenario’s vastleggen. Naast de normale gang van zaken worden de uitzonderingen beschreven: storing, dubbele berichten, gewijzigde gegevens en verwijderingen.
Bouwen in een testomgeving. De koppeling wordt gemaakt tegen een testversie van het andere systeem, zodat er niets in de echte administratie belandt.
Testen met echte gegevens. Er wordt getest met een representatieve set, inclusief de rommelige gevallen die in elke database voorkomen.
Live zetten en bewaken. De koppeling gaat in gebruik met logging en meldingen, meestal met een periode van verscherpt toezicht.

Wanneer heb je dit nodig?

De duidelijkste aanleiding is dubbel invoeren. Als iemand gegevens uit de website overtypt in een ander systeem, is dat tijd die verloren gaat en een bron van fouten. Zodra dat dagelijks werk is, verdient een koppeling zich meestal binnen afzienbare tijd terug.

Een tweede aanleiding is voorraad of prijzen die actueel moeten zijn. Een webshop die verkoopt wat er niet is, kost klanten en herstelwerk. Dat vraagt een verbinding met het systeem waar de werkelijke voorraad in staat.

Ook een klantportaal vraagt vrijwel altijd koppelingen, omdat de gegevens die klanten willen zien in interne systemen staan. En bij groei wordt het onvermijdelijk: handmatige overdracht die bij honderd orders per maand werkt, houdt bij duizend geen stand.

Wat levert het op?

De opbrengst is concreet en meestal goed te berekenen: minder handwerk, minder overtypfouten en actuelere gegevens op de plek waar ze nodig zijn. Bij organisaties waar iemand dagelijks gegevens overzet, is de terugverdientijd doorgaans kort. Daarnaast maakt het zaken mogelijk die met de hand niet haalbaar zijn, zoals actuele voorraad tonen of klanten hun eigen dossier laten inzien.

Wat erbij hoort, is een blijvende afhankelijkheid. Elke koppeling verbindt jouw site aan een systeem dat door iemand anders wordt beheerd en gewijzigd. Als die leverancier zijn API aanpast, moet jouw koppeling mee, en dat komt vrijwel altijd op een ongelegen moment. Koppelingen vragen daarom bewaking en een budget voor aanpassingen, ook als er verder niets verandert aan de site. Bureaus die een koppeling begroten als eenmalige post zonder onderhoudsafspraak, laten een reëel deel van de kosten buiten beeld.

Waar let je op als je dit uitbesteedt?

Vraag als eerste of er een bestaande koppeling of een tussenplatform beschikbaar is. Voor veelgebruikte combinaties bestaan kant en klare oplossingen die door de leverancier worden onderhouden, en dat is vrijwel altijd goedkoper en robuuster dan maatwerk. Laat maatwerk pas overwegen als vaststaat dat het bestaande aanbod niet volstaat.

Vraag vervolgens expliciet hoe fouten worden afgehandeld. Wat gebeurt er als het andere systeem uitvalt, wordt er opnieuw geprobeerd, gaan gegevens verloren, en wie krijgt een melding. Dit is de vraag die het meest bepaalt of een koppeling in de praktijk bevalt, en tegelijk de vraag die het minst wordt gesteld. Vraag ook naar documentatie en naar wie de sleutels beheert. Leg ten slotte vast wat er gebeurt als de leverancier van het andere systeem iets wijzigt: valt aanpassing onder onderhoud of is het meerwerk.

Veelgemaakte fouten

Bij koppelingen komen de problemen vrijwel nooit uit de normale gang van zaken, maar uit alles daarbuiten.

Alleen de gelukkige route bouwen. Een koppeling die alleen werkt als alles klopt, valt stil bij de eerste storing en laat gegevens ongemerkt verdwijnen.
Geen bewaking inrichten. Zonder melding bij stilstand komt een organisatie er pas achter als klanten bellen, soms dagen later.
De kwaliteit van bestaande gegevens overschatten. Elke database bevat afwijkende, incomplete en dubbele records, en die komen bij de eerste echte synchronisatie boven.
Onderhoud niet regelen. Wijzigingen aan de andere kant zijn onvermijdelijk, en zonder afspraak daarover ligt de koppeling stil tot er een opdracht is verstrekt.

Wat bepaalt de prijs?

De prijs volgt uit het aantal koppelingen en vooral uit de kwaliteit van de systemen aan de andere kant. Een goed gedocumenteerde moderne API is een fractie van het werk van een verouderd pakket zonder aansluitpunt.

Wat de prijs opdrijft	Waarom het meetelt
Kwaliteit van de bestaande API	Een ontbrekende of slecht gedocumenteerde API vraagt omwegen die veel uitzoekwerk en testtijd kosten.
Aantal velden en systemen	Elk veld moet worden afgebeeld en getest, en elk extra systeem vermenigvuldigt de combinaties.
Realtime in plaats van periodiek	Onmiddellijke uitwisseling vraagt zwaardere foutafhandeling en maakt storingzoeken complexer.
Tweerichtingsverkeer	Gegevens die aan beide kanten kunnen wijzigen, vragen regels voor welke versie voorgaat bij conflicten.

Koppelingen worden vaak op uurbasis gebouwd, omdat de omvang pas blijkt tijdens het uitzoekwerk. Waar op projectbasis wordt gewerkt, is het verstandig een aparte, kortere opdracht voor het vooronderzoek te vragen voordat de bouw wordt begroot. Reken daarnaast op een doorlopende post voor bewaking en aanpassingen. Vraag expliciet of aanpassing aan wijzigingen van derden daaronder valt, want dat is de kostenpost die het vaakst onverwacht terugkomt.

Koppelingen en API’s en aanverwante diensten

Koppelingen zijn zelden een losse opdracht en hangen aan het systeem eromheen. Backend en maatwerk is waar koppelingen technisch thuishoren, en in veel maatwerkprojecten vormen ze de grootste post. E-commerce platforms vragen ze vrijwel altijd, voor voorraad, prijzen, betalingen en verzending. Headless en Jamstack steunt er volledig op, omdat de scheiding tussen inhoud en presentatie via API’s verloopt. Hosting en onderhoud raakt eraan via de bewaking: een koppeling die stilvalt hoort een melding op te leveren. En webdevelopment is de bredere noemer waaronder bureaus dit meestal aanbieden. Vrijwel elk bureau dat maatwerk bouwt, doet koppelingen, maar de ervaring met specifieke pakketten verschilt sterk en is het navragen waard.