Wat is een API?
API is een Engelse afkorting, van "application programming interface". In gewone taal: een afgesproken manier om iets te vragen aan een ander systeem.
Vergelijk het met een loket bij de gemeente. Je loopt niet zelf het archief in. Je vult een vast formulier in en krijgt een antwoord in een vaste vorm terug. Een API werkt net zo:
- Het loket is een vast adres op internet, zoals dat van de betaaldienst Mollie.
- Het formulier is de vraag in een vaste vorm. Welke velden erin staan, staat in de handleiding van de API.
- Het antwoord komt ook in een vaste vorm terug. Vaak is dat JSON: een tekstvorm voor gegevens die mensen en computers allebei kunnen lezen.
- Het briefje bij een fout is een code, zoals "niet gevonden", "geen toegang" of "te veel vragen, wacht even".
Het andere systeem hoeft niet te weten hoe jouw systeem van binnen werkt. Ze kennen alleen het formulier. Daardoor kun je systemen van verschillende bedrijven aan elkaar koppelen. En het kan twee kanten op: het andere systeem kan jou ook een seintje geven, zoals Mollie doet als een klant heeft betaald.
Een sleutel: wie mag wat?
Bij de meeste API's moet je laten zien wie je bent. Dat doe je met een sleutel: een lange, geheime reeks tekens die bij elke vraag meegaat. In vaktaal heet dat een token. Het loket kijkt naar de sleutel en weet dan wie er vraagt en wat die mag.
Met de sleutel van een betaaldienst kun je geld terugbetalen, met die van een webshop producten aanpassen. Daarom blijft een sleutel geheim, net als de pincode van je bankpas. Wie hem heeft, kan doen alsof hij jou is.
Zo gaan wij ermee om:
- Niet in de code. Sleutels staan in een apart bestand op de server, los van het programma zelf. De geheime gegevens zet je broer zelf neer.
- Rechten pas als het nodig is. Bij Shopify bepaal je per sleutel wat hij mag. Komt er een taak bij, zoals retouren inzien, dan is er een nieuwe sleutel nodig.
- Kort geldig waar het kan. Bij bol krijgt ons voorraadsysteem een sleutel die ongeveer vijf minuten geldig is. Daarna haalt het vanzelf een nieuwe.
Soms zijn wij zelf het loket. Voor PandInfo bouwden we een eigen API voor de systemen van makelaars. Een makelaar ziet zijn sleutel één keer, bij het aanmaken. Wij bewaren alleen een soort vingerafdruk ervan, waaruit je de sleutel niet kunt terugrekenen.
Waar wij het voor gebruiken
Veel van wat we bouwen, praat met een ander systeem. Het gaat hier niet om de namen, maar om de techniek erachter.
- Voorraadsysteem.com: verkopen, voorraad en labels. Ons voorraadsysteem praat via een API met Shopify en bol: bestellingen komen binnen, de voorraad gaat terug. Verzendlabels komen via de API van MyParcel. Elke dienst heeft zijn eigen loket en eigen regels.
- Betalen bij PandInfo en Lichthoek. De site vraagt Mollie om een betaling klaar te zetten, de klant betaalt bij Mollie, en Mollie geeft de site een seintje. Daarin staat alleen een nummer. De stand van de betaling vraagt de site daarna zelf op bij Mollie. Zo kan niemand met een nepbericht laten denken dat er betaald is.
- Nummerbordcheck.nl: open gegevens van de RDW. De RDW zet een groot deel van het kentekenregister online, met een API zonder sleutel. Vul je een kenteken in, dan vraagt onze server meerdere tabellen tegelijk op en zet de antwoorden op één pagina. Een foto van het model komt via de API van Wikipedia, ook via onze server. De bezoeker praat dus alleen met ons.
- PandInfo: meer dan dertig bronnen. Een adres intypen zet vragen uit bij PDOK en het Kadaster, het CBS, het energielabelregister van RVO, de Omgevingswet en meer. Veel van die bronnen zijn open. Voor een paar hebben we een eigen sleutel aangevraagd.
- Lichthoek: adres controleren en bestellingen doorgeven. Bij het afrekenen controleert Lichthoek postcode en huisnummer in de officiële adressenlijst, via PDOK van het Kadaster. Alleen postcode en huisnummer gaan daarheen, geen naam of e-mailadres. Een betaalde bestelling gaat via een API naar het voorraadsysteem, en de track-and-trace komt langs dezelfde weg terug. Die API ontwierpen we zelf.
Als een API verandert of even niet werkt
Een API is van een ander bedrijf. Dat bedrijf kan hem aanpassen, en soms is hij even niet bereikbaar. Daar houden we vanaf het begin rekening mee.
Even geen antwoord. Elke vraag heeft bij ons een tijdslimiet. Wat er daarna gebeurt, kiezen we per geval.
- Bij Nummerbordcheck.nl zie je dan een nette pagina: de RDW antwoordt niet, probeer het over een minuut opnieuw. Valt alleen een bijtabel weg, dan zie je de rest gewoon.
- Bij PandInfo geeft het energielabelregister soms pas na acht seconden antwoord. Bij een storing vragen we het daarom nog één keer, met een langere wachttijd. Lukt dat ook niet, dan staat er in het rapport een nette melding met waar je het label zelf kunt opzoeken.
- Bij Lichthoek houdt een storing bij PDOK de bestelling niet tegen. De bestelling krijgt dan een vlag "niet gecontroleerd".
Te veel vragen. Veel API's hebben een grens: zoveel vragen per minuut. Ga je erover, dan krijg je de code "wacht even". Bol stuurt mee hoe lang, en ons voorraadsysteem wacht precies zo lang. Zelf houden we ook rekening met de ander: Nummerbordcheck.nl bewaart een antwoord van de RDW een kwartier, zodat verversen de RDW niet onnodig belast. En onze eigen API voor makelaars bij PandInfo neemt per sleutel hooguit zestig vragen per minuut aan.
Opnieuw proberen, zonder dubbel. Een betaalde bestelling van Lichthoek naar het voorraadsysteem gaat via een wachtrij. Lukt het niet, dan probeert de winkel het opnieuw: na een minuut, dan na twee, vijf en tien minuten, en zo steeds wat later, tot eens per twaalf uur. Maar opnieuw proberen mag geen dubbele bestelling geven. Daarom heeft elke bestelling een vast nummer, en het voorraadsysteem herkent een bestelling die het al heeft. Bij Shopify gaat er een vaste code mee die bij een nieuwe poging gelijk blijft.
Een fout die opnieuw proberen niet oplost. Klopt de sleutel niet, of is het bericht zelf fout, dan heeft nog een keer proberen geen zin. De koppeling tussen Lichthoek en het voorraadsysteem stopt dan met proberen en zet een melding in het beheer.
Een API die verandert. Grote diensten geven hun API een versie. Bij bol gebruiken we nu versie 10, bij Shopify een versie met een datum erin. Die versie staat vast in ons programma. Komt er een nieuwe, dan passen we het aan en testen we opnieuw voordat het live gaat. Voor onze eigen API tussen Lichthoek en het voorraadsysteem is de afspraak: velden en foutcodes veranderen niet stilletjes.
In de gaten houden. We houden in de gaten of alles draait, en grijpen in als het nodig is.
Zo bouwen we het
- Eerst de handleiding. We lezen hoe de API werkt: welke vragen, welke antwoorden, welke grenzen en welke foutcodes.
- Zo weinig mogelijk delen. We sturen alleen wat nodig is, zoals alleen postcode en huisnummer naar PDOK. Gegevens die een klant in zijn site of systeem bij ons zet, delen we niet met de AI-hulp waarmee we bouwen.
- Testen zonder echte gevolgen. We testen met verzonnen gegevens in dezelfde vorm als de echte. Met de echte gegevens kijkt je broer zelf. Een betaling testen we in een proefstand, zonder echt geld. Bij MyParcel kost een zending wel echt geld, dus maakt het voorraadsysteem daar pas een zending aan na een klik.
- Live na controle. We bouwen met hulp van AI. Elke wijziging gaat eerst door onze tests. Daarna leest een aparte AI-hulp alles nog eens na, en live gaat het pas na het akkoord van je broer.
- Draaien op onze eigen server. Een koppeling die moet blijven werken, draait op onze eigen server, in een datacenter binnen de EU. Wat er binnenkomt, slaan we op in een database. Daarover lees je meer bij databases.
Wat jij ervan merkt
Als het goed gaat: bijna niets. Een bestelling staat vanzelf in je systeem, de voorraad klopt op elk kanaal, en een klant krijgt zijn track-and-trace zonder dat iemand iets overtypt.
Gaat het even mis bij de ander, dan krijgt je bezoeker waar het kan een nette melding in plaats van een foutscherm.
Wat het kost
Voor veel systemen hebben we al een koppeling klaarstaan. Die vind je bij koppelingen en automatisering. Wil je iets koppelen waar nog niets voor bestaat? Dan is het een koppeling op maat: vanaf € 395, daarna € 10 per maand.
Een koppeling moet blijven draaien, dus hij zit in een pakket. Kleine broer, vanaf € 19 per maand plus eenmalig bouwen vanaf € 495, is voor één koppeling tussen twee systemen. Grote broer, vanaf € 68 per maand en zonder opstartkosten, is je eigen omgeving. Alle bedragen zijn exclusief btw. Je krijgt altijd eerst een offerte.
Wat we eerder bouwden
- Voorraadsysteem.com. Onze eigen voorraadsoftware, met koppelingen aan Shopify, bol en MyParcel.
- PandInfo. Meer dan dertig openbare bronnen achter één zoekvak, betalen via Mollie, en een eigen API voor makelaars.
- Nummerbordcheck.nl. Een gratis kentekencheck op de open gegevens van de RDW.
- Lichthoek. Een webshop die via een API met het voorraadsysteem praat: producten erin, bestellingen eruit.
