5. API’s van meerdere kanten belicht
Wat zijn API’s en waarom zijn organisaties tegenwoordig API-Driven?
--
Aleksandra is druk met haar webshop met taarten en cakes. Om nieuwe cakes te delen had ze al snel een Instagram account aangemaakt. Maar er zijn ook nog veel andere kanalen, zoals LinkedIn, Twitter, Facebook en Pinterest. Als ze alle posts handmatig in alle kanalen moet zetten, blijft er weinig tijd voor bakken over. Makkelijker is één post op haar eigen website te maken om die vervolgens via de API’s van de verschillende sociale media kanalen te delen.
Vrijwel alle social media, zoals Facebook en Twitter bieden een API aan. Deze kan je aanroepen om bijvoorbeeld een tweet te plaatsen. Nu kun je natuurlijk ook gewoon op de Twitter-website inloggen en een tweet achterlaten: “superlekkere taarten”, maar je kunt dit dus net zo goed via een API doen, vooral als je dit wilt automatiseren.
Vrijwel alle organisaties stellen hun functionaliteit tegenwoordig beschikbaar via API’s. Voorheen deden alleen grote tech-bedrijven zoals Twitter dit, tegenwoordig doet de bakker om de hoek dit ook. Het is dus alomtegenwoordig, maar wel echt een andere manier van het bedrijven van integratie. Daarom behandelen we dit onderwerp in een apart hoofdstuk.
Wat is een API?
Een programmeur schrijft al snel een script om zijn werk te automatiseren. De regels code in zo’n script worden eenvoudigweg door een computer onder elkaar uitgevoerd. Om sommige acties op meerdere plekken uit te voeren, maakt de programmeur een generieke functie. Bijvoorbeeld het loggen van allerlei informatie.
Al snel blijkt dat deze functie ook in andere scripts handig is. De verschillende generieke functies verzamelt hij tenslotte in een library die vanuit allerlei scripts aangeroepen kan worden. In de basis zit achter elke API dan ook een library met generieke functies.
Een API (Application Programming Interface) is:
“A set of clearly defined methods of communication between various software components. A good API makes it easier to develop a computer program all the building blocks, which are then put together by the programmer”. (Wikipedia)
Een API is in basis dus een verzameling functies. En het gebruik van API’s is gegroeid vanuit het modulair opzetten van applicaties.
Een API gaat nog een stap verder dan het puur maken van een library. Ten eerste maakt een API een duidelijk verschil tussen publiek toegankelijke functies en interne functies. Ten tweede abstraheert een API de implementatie van deze functies door een interfacelaag er bovenop te leggen. Deze is gericht op de clients die deze functies aanroepen.
Een API is de etalage met alle functies die een applicatie biedt. Net als een etalage met alle taarten die te koop zijn.
Al sinds de jaren 70 worden API’s in allerlei programmeertalen, zoals bijvoorbeeld C, geschreven. In Java is zelfs het maken van een API onderdeel van de taal zelf. Het maken van een lijst van functies heet daar “interface”.
De structuur van een programma dat een API gebruikt ziet er als volgt uit:
Webservices
Er kleeft een sterk nadeel aan de API’s van programmeertalen. De programma’s die de API’s aanroepen, moeten in dezelfde taal zijn geschreven. Zo maakt de broker ActiveMQ gebruik van de Java API “JMS”. De programma’s die deze API aanroepen moeten dan ook in Java zijn geschreven.
Een uitweg uit dit probleem is de functies beschikbaar te stellen via het internet. Dit is bekend onder de naam webservices. Het aanroepen van zulke functies lopen via HTTP requests. De eerste webservices maakten gebruik van XML. Zij definieerden een webservice met SOAP (Simple Object Access Protocol). Tegenwoordig zijn REST webservices, ook wel REST API’s, de standaard.
REST Webservices
REST is een architectuurstijl om via HTTP requests data naar een API te sturen, te verwijderen of op te halen. Deze architectuurstijl werd in 2000 ontwikkeld door Roy Fielding voor zijn proefschrift. In dit onderzoek beschrijft Roy hoe software met andere software kan communiceren.
De afkorting REST staat voor REpresentational State Transfer. Maar deze afkorting brengt ons niet veel verder om te begrijpen wat het is. Beter is te bekijken welke software componenten precies met elkaar communiceren. Dit is een client (bijvoorbeeld software op de telefoon, laptop of server) met een webserver (De REST Webservice):
Een HTTP Request bestaat uit de volgende onderdelen:
- Actie
Het type actie dat moet worden uitgevoerd. De meest gangbare acties zijn GET, POST, PUT of DELETE. Het HTTP responsebericht bevat het antwoord van de API.
2. Endpoint
Een endpoint heeft meestal de vorm van een internetadres:
3. Headers en Body (optioneel)
Het request dat de aanvraag doet kan ook headers en een optionele body bevatten.
Resources
Op de web server zit achter het endpoint een resource. Resources vormen de kerndata waarmee je applicatie werkt, zoals een factuur of een artikel. Meerdere resources worden weer een collectie genoemd. Een verzameling van REST endpoints en collecties is de REST API.
Meer achtergrondinformatie over REST
REST API’s: voor- en nadelen
Voordelen
Één van de belangrijkste voordelen van REST API’s is dat ze gebruik maken van internetstandaarden. Hiermee zijn ze technologie-onafhankelijk. Dit maakt ze niet alleen onafhankelijk van infrastructuur, maar ook van programmeertalen. Een aanroep kan vanuit een .Net applicatie gedaan worden op een REST API met daarachter een Java-applicatie. Omdat de URI via het internet wordt gebruikt kan de hardware resources overal worden geplaatst en opgeschaald.
REST is ook populair, omdat het in basis maar een beperkt aantal acties bevat, namelijk GET, POST, PUT en DELETE. Deze zijn snel in te bouwen en sluiten goed aan op de databaselaag.
Er kunnen ook meerdere applicaties op dezelfde API aangesloten worden. Deze kunnen bijvoorbeeld een artikel op vragen. Een aanroep is bijvoorbeeld:
GET http://example.nl/api/artikel?type=basis
Deze aanroep geeft de basisinformatie van een artikel terug. Een andere applicatie kan een uitgebreider verzoek doen:
GET http://example.nl/api/artikel?type=all
Nadelen
Net als bij het maken van een database of programma vereist het opzetten van een API veel werk en tuning. En net als bij de genoemde integratietechnieken in het vorige hoofdstuk, vormt het verkeerd opzetten later een probleem. Het nadeel is zelfs nog groter, omdat er meerdere programmeeropties mee verbonden zijn. Het is geen een-op-een-koppeling:
“REST does not help you organize things. It forces you to use API supported by server-side library you are using. You can organize your application the same way (or better) when you are using non-REST approach. It all depends on how well you organize and document your application. REST will not magically make your application better.”
REST maakt gebruik van HTTP. Dit protocol staat er ook om bekend dat het geen duidelijke definities biedt voor acties en foutcodes. Er bestaan bijvoorbeeld geen regels die aangeven wanneer je POST en wanneer je PUT moet gebruiken. Buiten GET, POST, PUT en DELETE zijn er ook nog andere acties, zoals PATCH en TRACE, maar die zijn vaak niet geïmplementeerd en kun je dus ook niet zomaar gebruiken.
Dezelfde onduidelijkheid geldt deels ook voor HTPP Response codes:
“Consider, for example, when we might use the 200 OK response code. Should we use it to indicate the successful update of a record, or should we use 201 Created? It seems we really should use a code like 250 Updated but that code doesn’t exist. And can anyone out there explained to me what 417 Expectation failed really means?”
Doordat er niet een heel strikte standaard is, kost het opstellen en debuggen van een REST service veel tijd. Een ander nadeel is dat een API als webservice weinig meer biedt dan het uitwisselen van data. Voor het loggen, bewerken, cachen, bufferen enzovoort zijn additionele tools nodig, meestal in de vorm van een API Management platform.
Een standaard voor REST die steeds meer gebruikt wordt is OData (Open Data Protocol). Door het gebruik van OData is het niet noodzakelijk om afspraken te maken over onder andere HTTP-methoden, URL-conventies, gebruikte mediaformaten en query-opties.
API als product
Een API is zeker niet alleen een technische component. Zoals aangegeven zit het voordeel er meer in dat het gebruik maakt van internetstandaarden en niet noodzakelijk in andere technische voordelen. Het grootste voordeel ligt echter aan de business-kant.
API’s zijn voor een applicatie wat de etalage is voor een winkel. Zie het als een lijst met daarop alle taarten die de bakkerij kan maken. Een klant loopt langs de winkel en ziet in de etalage allerlei taarten staan. Deze taarten (en ze hoeven niet eens echt te zijn) moeten er aantrekkelijk uit zien en overzichtelijk zijn gepresenteerd.
Iemand die een API gebruikt wordt daarom meestal “consumer” genoemd. Om deze redenen is het gebruikelijk om een API te ontwerpen als een product voor een consument. Meerdere API endpoints moeten consistent en helder zijn voor degenen die ze gaan gebruiken. De gebruiker van een API is over het algemeen een ontwikkelaar. Een API geeft een ontwikkelaar inzicht in welke functies een applicatie allemaal beschikbaar heeft.
Developer portal
Stel je wil een groot feest geven waarvoor Aleksandra een aantal taarten maakt. Traditioneel zou je haar opbellen en met haar afspreken welke taarten je nodig hebt. Tegenwoordig kan dit echter helemaal digitaal via de website (user interface) of een API (data interface).
Ook bij traditionele integraties kwamen vaak projectleiders, architecten en ontwikkelaars fysiek bij elkaar voor de afstemming. Bij API’s gaat alles digitaal. Een ontwikkelaar publiceert zijn API in het zogenoemde ontwikkelaarsportaal. En andere ontwikkelaar logt in op dit portaal en onderzoekt de verschillende API’s (de etalage). Vervolgens past hij zijn eigen programma (de client) hierop aan.
Een API wordt zo gemaakt dat andere ontwikkelaars die kunnen gebruiken. Het idee is dat ontwikkelaars een API zelf kunnen verkennen en gebruiken. Deze etalage wordt ook wel ontwikkelaarsportaal of developer portal genoemd. Maar hoe maak je zo’n portaal?
Een developer portal heeft duidelijke specificaties, zodat die getoond kunnen worden. Bekende specificaties zijn:
Met behulp van deze specificaties kan de API worden ontworpen en vervolgens kan daaruit documentatie worden gegenereerd. Deze documentatie wordt ten slotte beschikbaar gesteld in de “Developer Portal”.
API Gateway
API’s staan in de developer portal (de etalage). Het is echter niet de bedoeling dat iedereen er zomaar data uit kan halen. Net zoals je niet zomaar iets uit de etalage kunt pakken, zul je bij API eerst toegang moeten krijgen, om de data op een veilige manier te delen.
De software die de etalages maakt en beheert is het API Management Platform. Het kerncomponent van dit platform is de API Gateway. Deze kwamen we al eerder tegen in het hoofdstuk “Technische integratie”. Een API gateway bevindt zich tussen clients en services. Technisch gezien fungeert het als een omgekeerde proxy, voor de routeringsaanvragen van clients naar services.
Een API Gateway wordt geconfigureerd in een API Manager. Hierin kun je bijvoorbeeld bepalen: wie krijgt toegang tot de API; wat gebeurt er als er iets mis gaat; en hoe regel je load balancing? Ook logging, versiebeheer en gebruiksstatistieken worden via de API Gateway in de API Manager bijgehouden.
API ≠ API Platform
Een API Management Platform is een verzameling tools voor het managen van de API-laag. Voorbeelden van zulke tools zijn API Tester, API Manager en API Gateway. Het is belangrijk te realiseren dat een API Platform zelf geen API’s bouwt of host.
API’s zijn in principe publieke functies van applicaties. Het API Platform zorgt dat deze centraal worden gemanaged. Daarom spreek je meestal niet over API Platform, maar over API Management.
Waarom API Management?
Er zijn meerdere manieren om een API-laag op te bouwen. Zijn er maar enkele API’s, dan kunnen ze elkaar gewoon rechtstreeks aanroepen. Zijn er meerdere API’s dan is een stuk beheer noodzakelijk. Dit beheer, het API Management, regelt alle zaken rondom de API. Denk hierbij aan publicatie, beveiliging en beheer:
“API management is the process of creating and publishing API’s, enforcing their usage policies, controlling access, nurturing the subscriber community, and collecting and analyzing usage statistics.” (Wikipedia)
Vrijwel alle grote software leveranciers, zoals Microsoft, Google en IBM, bieden een API Management-product aan. Bekende open source-spelers op dit gebied zijn Mule, 3Scale, WS02, TYK en Kong.
API Management zorgt ervoor dat je de regie in het beheer van je API’s behoudt. Vanuit technisch en beheersoogpunt is het duidelijk waarom je API Management nodig hebt. Je moet immers je omgeving kunnen schalen, maar ook inzichtelijk houden als er iets mis gaat.
De belangrijkste componenten van API Management zijn:
- API Designer
- API Gateway
- API Tester
- API Manager
- API Portal
In het ontwikkelproces van API’s worden de verschillende componenten gebruikt.
API Manager
Als je met API’s gaat werken zijn er twee belangrijke vragen:
- Hoe zijn de API’s ontworpen?
- Hoe worden de API’s beheerd?
In het begin liggen deze twee zaken heel dicht bij elkaar. Met name tussen maatwerk-applicaties, omdat daar makkelijker afspraken over de inrichting kunnen worden gemaakt. Zodra er meerdere API’s ontstaan en er meerdere applicaties op worden aangesloten, wordt het management ervan steeds belangrijker.
De API Manager zorgt voor:
- Traffic management
- Routeren van requests
- Rate limiting
- Throttling
- Authenticatie
- Foutafhandeling
2. API Management
- Policies
- SLA’s
- Contract Management
- API Versiebeheer
3. Security & Governance
- Encryptie/Certificaten (Mutual TLS)
- Edge protection (Bijvoorbeeld tegen DDoS aanvallen)
- Audit logs
4. Analytics & Monitoring
- Troubleshoot & Monitoring
- Functionele tests
- Logging & Tracing
- Alerts & Notificaties
5. Combineren van API’s
- Interactieve API docs
- User Engagement
De API manager configureert de API Gateway. Deze zorgt voor al het dataverkeer en zorgt ervoor dat de API Consumer en Provider van elkaar ontkoppeld zijn. Dit staat bekend als het HATEOAS-principe.
API Economy
Stel een fabriek maakt allerlei grondstoffen en benodigdheden voor bakkerijen. Deze fabriek kan op zoek gaan naar allerlei afnemers. Die afnemers willen natuurlijk weten wat voor type ingrediënten en benodigdheden de fabriek verkoopt en wat ze kosten. Afnemers kunnen bakkerijen zijn, maar misschien ook groothandels die de productinformatie willen laten zien op hun website.
Nu kan de fabriek voor elke afnemer een integratie gaan maken, maar het kan ook één API ter beschikking stellen. Alle verschillende afnemers kunnen zo de informatie opvragen die ze willen en integreren in hun eigen systemen. Ook kunnen ze de API gebruiken om bestellingen te plaatsen.
Het mooie is dus dat er maar één API voor alle afnemers is. Daarnaast is het mooi dat afnemers het kunnen gebruiken zonder tussenkomst van de fabriek. Sterker nog: de fabriek hoeft helemaal niets van de afnemer te weten. Zo krijgt men plotseling orders vanuit regio’s waar de fabriek niet actief is. De data van de fabriek kan dus in heel verschillende context worden gebruikt, zelfs in een context die niet van tevoren door de aanbieder van de API was voorzien.
Het bedrijfsmodel en de best practices rondom het gebruik van API’s worden ook wel “API-Economy” genoemd. De API is dus voor de fabriek zelf ook een product. Door API’s als producten te zien werkt data uitwisseling anders dan bij traditionele integraties. Integraties zijn aanbod-gedreven componenten, terwijl API’s meer vraag-gedreven componenten zijn.
Type API’s
Vanuit de verschillende behoeftes om API’s te consumeren, zijn er verschillende type API’s ontstaan. De verschillen in behoefte ontstaan door wie een API aanroept en waarmee. De belangrijkste vragen om te bepalen welke type API wordt ontworpen, zijn:
- Wordt een API intern of extern gebruikt?
- Wordt een API door systemen of in processen gebruikt?
- Wordt een API door een mobiele app of een webapplicatie gebruikt?
Vanuit deze behoeftes worden er drie lagen onderscheiden:
- System API’s
Deze API’s ontsluiten zogenoemde System of Records, denk aan ERP- en CRM-systemen. Dit is het laagste niveau. Vaak zijn deze API’s alleen intern te benaderen.
2. Process API’s
De process API’s communiceren met meerdere system API’s om van daaruit een business process te bouwen.
3. Experience API’s
Een laag boven op de Process API’s die API’s aanbieden voor een specifiek “channel”. Denk aan mobile of desktop.
Deze terminologie komt van Mulesoft, maar is inmiddels ook door veel andere aanbieders overgenomen.
Samengevat is een API:
- Een digitaal product
- Consumer-oriented
- Self-service
Inhoudsopgave:
