Dit is deel twee van het artikel over een veel gebruikte manier om systemen met elkaar te verbinden, namelijk door middel van een api.
In het eerste deel heb ik uitgelegd dat api een afkorting is voor Application Programming Interface, met andere woorden een manier om een verbinding te maken tussen systemen of applicaties. Hoewel de definitie niets zegt over de manier van verbinding leggen, ga ik voor dit artikel uit van de REST architecturale stijl. REST staat in dit geval voor REpresentational State Transfer. REST werkt met HTTP Verbs zoals POST, GET, PUT en DELETE om data te manipuleren of op te vragen. Deze verbs lijken qua functionaliteit wel wat op de essentiële database operaties: Create, Read, Update en Delete (CRUD).
PostNL
Een bedrijf als PostNL biedt diverse api’s aan, We nemen als de api waarbij we data halen uit de postcodetabel. Als gebruiker van dit systeem heb je eigenlijk alleen maar de mogelijkheid om te lezen en niet om een update te doen. In dit geval doen we dus een POST op de api van PostNL met daarbij natuurlijk een aantal velden.
Waarom geen GET? Nou voor een gedeelte is dat een ontwerpkeuze. Een POST kent een zogenaamde payload die wordt meegestuurd, in dit geval een drietal velden in JSON layout. JSON is een veel gebruikte manier om data te annoteren. Hierboven zie je dat een landcode, postcode en huisnummer worden meegestuurd, Die parameters kunnen in dit geval zijn (1) een postcode waarbij we een adres zoeken of (2) een adres waarbij we een postcode zoeken. Het voordeel van deze api is dat je een eenduidige opslag krijgt van adresgegevens waar geen fouten in staan. De data komen uit het postcodebronsysteem.
Geen api-politie
Maar, organisaties zijn vrij om de api zo te ontwikkelen als ze zelf willen. Er is geen api-politie anders dan de afspraken die je maakt als organisatie met betrekking tot het gebruik van api’s. Daarin kan je de do’s en dont’s afspreken die je als organisatie in acht neemt. Dan kun je ook afdwingen dat een POST niet wordt gebruikt voor informatie ophalen, maar voor het toevoegen van data aan een collectie. Hoe meer je je aan algemeen begrijpelijke afspraken houdt, des te makkelijker is de api te begrijpen, zowel binnen als buiten de organisatie.
Maar hoe zit het dan als je een postcode wilt toevoegen? Want er ontstaan nieuwe wijken met huizen en bedrijven die ook aan het postcodes systeem moeten worden toegevoegd. Natuurlijk is er ook een api voor maar die wordt niet met ontwikkelaars buiten de organisatie gedeeld. Deze api is er voor de interne organisatie die deze tabel bijhoudt. Ook hierbij kan je weer keuzes maken, zijn dit twee verschillende api’s of is het een api die voor diverse groepen anders gerepresenteerd wordt.
Zet je schrap voor gesprekken met de architecten.
Glimmende voorkant
Je zou misschien denken dat een api altijd ‘state of the art’ technologie is. Tenslotte zijn api’s modern vergeleken met andere manieren van het benaderen van informatie zoals bijvoorbeeld het SOAP-protocol. En daar kun je je in vergissen. Een api is eigenlijk per definitie de interface naar de ontsluiting van een achterliggend systeem en daarnaast ook de beschrijving van de interface. En dat kan een modern systeem zijn, bijvoorbeeld een artificial intelligence (ai)-toepassing die op basis van deep learning geautomatiseerd beeldherkenning kan doen. Maar dat hoeft absoluut niet.
Wat er achter de api ligt is niet noodzakelijk de nieuwste technologie Het is eigenlijk een moderne manier van ontsluiten maar het systeem wat je ontsluit het zou best wel eens een heel oud polis administratiesysteem zijn bij een verzekeraar, jaren geleden ontwikkeld en nu voorzien van een api om verzekerden via een website bijvoorbeeld inzicht te geven in hun polis.
Een ander voorbeeld is het ontsluiten van een database bijvoorbeeld IMS DB. Deze database is ontwikkeld In de jaren 60 en kan ook door middel van een api ontsloten worden. De achterliggende logica zorgt voor het ophalen van de informatie (de verbinding met de backend). Dit zou bijvoorbeeld op een ESB (Enterprise Service Bus) kunnen gebeuren waarbij deze de verbinding en ontsluiting regelt. De api-interface is niets meer dan de glimmende voorkant, wat er aan de achterkant gebeurt kan best een stuk legacy-technologie zijn.
Owasp
Een onderwerp wat niet mag ontbreken als je het over api’s hebt is Owasp, een acroniem van Open Worldwide Application Security Project. Dit is een stichting die werkt aan het verbeteren van de beveiliging van software. De relevantie met api’s is de Owasp 2023 Security Vulnerabilities-lijst. Dit is een lijst zijn de meest gemaakte fouten die zijn gevonden met betrekking tot de beveiliging van api’s. Op Github vind je de lijst met als je doorklikt meer informatie maar ook online zijn er veel blogs en webinars te vinden hierover.
Wat je je hierbij moet voorstellen? Bijvoorbeeld het teruggeven van te veel data uit een database. In plaats van de gevraagde data, bijvoorbeeld de prijs van een artikel bij een bedrijf, ook de inkoopprijs of marge teruggeven. De app kan dit uitfilteren maar de api geeft de informatie wel, dus als die direct wordt aangeroepen (via een tool) kan deze informatie zichtbaar worden. Een andere is een foutmelding van de backend die de api niet uitfiltert. Hierdoor kan informatie over gebruikte systemen/ddatabases worden gelekt. Dit is waar een hacker naar op zoek is. Als je meer wilt lezen over hoe hackers dat doen, het boek Hacking APIs van Corey Ball is een aanrader. Maar laat je hierdoor niet afschrikken! Want api’s bieden veel waarde.
Gebruiken of ter beschikking stellen?
Er kan dus een situatie zijn dat jij als organisatie een api ter beschikking stelt, bijvoorbeeld om informatie aan te bieden. De redenen hiervoor zijn divers, zoals het klanten inzicht geven in bepaalde gegevens. Daardoor zijn ze in staat om een aantal vragen zelf te beantwoorden of handelingen uit te voeren. Dat scheelt de organisatie tijd. Een ander voorbeeld is het geven van toegang aan partners waarmee je samenwerkt zodat zij hun informatie direct aan het systeem kunnen toevoegen.
In mijn training gebruik ik voorbeelden van api’s van Starbucks, Rijksmuseum en Clarifai. De app van Starbucks stelt klanten in staat om met hun mobiele telefoon een koffie te bestellen, te betalen, af te halen in de winkel zonder In de rij te staan. Deze app gebruikt een api die Starbucks in staat stelt het bestellen van koffie vanuit een mobiele app te beveiligen, en daardoor meer koffie te verkopen, zonder dat de rijen noodzakelijkerwijze langer worden. De api optimaliseert de processen en zorgt voor meer omzet.
Het Rijksmuseum daarentegen heeft, zover ik weet, bij het ontwikkelen van zijn api geen commerciële doelstellingen. De api, onderdeel van de online-collectie-omgeving Rijksstudio, stelt gebruikers in staat om informatie over de meer dan 250.000 gedigitaliseerde kunstobjecten op te vragen. Dit is een echte GET met als parameters de taal waarin de informatie moet worden teruggegeven, het objectID en de api-key als gebruikersidentificatie.
Het antwoord als het object is gevonden, luidt: wie heeft het gemaakt, wanneer is het gemaakt, wie staat erop en natuurlijk een link naar het gedigitaliseerde object, plus nog een aantal andere velden. Doelstelling is om de kunst zo breed mogelijk te verspreiden onder de mensen en er zoveel mogelijk mensen van te laten genieten. Als iemand daarna besluit om naar het Rijksmuseum te gaan dan is dat mooi maar (volgens mij) geen primaire doelstelling.
Clarifai
Als laatste voorbeeld van een api gebruik ik die van Clarifai, een spin-off van New York University die een systeem heeft ontwikkeld dat in staat is geautomatiseerd foto’s en video’s te annoteren met de daarop zichtbaar personen objecten of plaatsen. In dit geval is deze api, waarbij je bijvoorbeeld foto’s of video ’s kunt uploaden om beeldherkenning te doen, de kern van het businessmodel van de organisatie. Hoe meer gebruik gemaakt wordt van de api (tegen betaling natuurlijk) des te beter is het voor Clarifai. Er bestaat wel een freemium model om het uit te proberen maar als je echt een grote data- of fotoverzameling hebt dan moet je er voor betalen om het te kunnen gebruiken.
Het voordeel voor de gebruiker is dat door middel van deze zogenaamde metadata van de beelden de collectie waardevoller wordt. Dat is een van de redenen dat onder andere een stockfotobedrijf als Getty Images zoveel tijd besteed aan het annoteren van een foto.
Aanbieden of gebruiken?
Maar er zijn ook situaties dat je een api gaat gebruiken. Bijvoorbeeld die van PostNL maar er zijn natuurlijk nog veel en veel meer waar je wat mee kunt doen. Zo heeft RDW een api om gegevens van gekentekende voertuigen op te vragen en ook het Kadaster heeft iets dergelijks.
Kortom, er is een wereld vol met api’s die je kunt gebruiken afhankelijk van jouw situatie als organisatie. Daarnaast kan je jezelf, zoals gezegd, een api ter beschikking stellen aan partijen die daar gebruik van kunnen maken. Dat kunnen bekende bedrijven zijn waarmee je zakendoet, maar ook aan gebruikers die je helemaal niet kent. Of je nu een api gaat gebruiken of aanbieden, het managen van api’s is wel een noodzaak.
In het volgende artikel ga ik in op wat api-management is en wat het kan bieden en hoe je dit kunt implementeren als je ook echt met een api aan de slag wilt gaan.
Auteur Rob Blaauboer is head of Training Services & Integration Consultant bij Yenlo.
