Je leest het heel geregeld op allerlei sites zoals hier op Computable: 'bedrijf XYZ biedt nu een api aan”. Maar wat is nou eigenlijk een api en wat kan je ermee? In dit tweedelige artikel zal ik meer uitleg geven over api's en wat je ermee kunt.
In een volgend artikel zoom ik in op hoe je met api’s moet omgaan. Maar dat is voor later zorg, Laten we eerst maar eens kijken wat een api eigenlijk is. Overigens, dit is niet een artikel voor de doorgewinterde REST-ontwikkelaar, daarvoor is het te basaal.
Definitie
Het is altijd goed om te beginnen met een definitie of een uitleg. Een api is een acroniem van application programming interface. Met andere woorden een api biedt een interface, een verbinding, aan naar een systeem om daar data in te stoppen of uit te halen.
Daarbij is het van belang dat daar in ieder geval vanuit de definitie niets wordt gezegd over op welke manier deze interface tot stand wordt gebracht. Voor alle duidelijkheid, als ik het heb over api’s dan praat ik over de zogenaamde ‘RESTful invocation’ dat wil zeggen communicatie op basis van de REST architecturale stijl.
Je kunt er een discussie over hebben of dit een niet te nauwe definitie is, want Gartner noemt onder andere ook GraphQL API, gRPC Webhooks en Kafka. Dit analistenbureau houdt zich meer aan de letterlijke definitie. Maar voor dit artikel denk ik dat het goed is om het zo te laten. Zeker ook omdat ik ga focussen op REST, RESTful en not truly RESTful.
REST en RESTful
REST is het eerst genoemd door Roy Fielding in zijn dissertatie in 2000. Fielding heeft meegewerkt aan de HTTP 1.0 en 1.1 specificaties en aan de ontwikkeling van Apache-webserver en heeft zijn sporen wel verdiend. Wat hij beschrijft zijn de constraints met betrekking tot REST:
- Uniform interface
- Client–server
- Stateless
- Cacheable
- Layered system
- Code on demand (optional)
Wil je weten wat dit inhoudt, lees dan dit blog. Er is natuurlijk nog veel meer van belang zoals het gebruik van resources. Ook het gebruik van mediatypes is onderdeel van REST, JSON wordt veelgebruikt maar dat is geen verplichting.
Het maakt gebruik van zogenaamde HTTP methods zoals GET, POST, PUT en DELETE en kent daarnaast resources die aangeven. Een college van mij maakte dit handige, bovenstaand overzicht. Het transport in dit geval is Https, het sub-domein is webapi. Yenlo is het domein en .com het TLD (toplevel domein, in dit geval de afkorting van Commercial). In het pad (path) vinden we de api- naam (MyProduct/v1), het resource path (myCollection/{myResource} en nog een query-parameter (?Param={param}. Alles tussen {en} zijn variabelen, de rest is vast.
Kortom, er is een aantal regels waar je als REST API aan conformeert maar ook nog veel vrijheidsgraden. Zo is er geen verplichting (maar wel meningen) dat de enige manier om informatie op te halen een GET is. Het Richardson Maturity Model (RMM) waar Martin Fowler hier over schrijft is een voorbeeld van een model om te zien hoe ‘RESTful’ je bent. Maar, zo je op een andere manier willen omgaan met REST, dan kan dat ook. Volgens RMM ben je op de lagere niveaus niet truly RESTful.
Heiligschennis
Er zijn mensen die een GET de enige manier vinden om informatie op te vragen en dat het gebruik van POST, heiligschennis is. Zoals hierbij het Rijksmuseum waar in een browser (doet een GET) informatie kan worden opgevraagd. De parameters staan in de URL zoals het object nummer SK-C-5 en, niet zichtbaar, de apiI key. Nadeel hiervan is dat zo’n URL in een log bestand ook de api-key toont wat niet ideaal is i.v.m. misbruik/ diefstal.
Een key als header is minder zichtbaar in een logbestand.
Hoe kom je aan een api?
Als we de api zien als de interface dan kan wat er wordt ontsloten van alles zijn. Een volledig nieuw ontworpen api waarbij de api-functionaliteit leidend is en de systemen volgend, of, wat heel vaak voorkomt, de functionaliteit die er is wordt voorzien van een api. Later komen we hier nog op terug.
Als een bedrijf een api ter beschikking stelt dan is deze benaderbaar over het internet via een url. Bijvoorbeeld: https://API.postnl.nl/address/v1/benelux
Wat opvalt bij deze url van PostNL is dat de url al een indicatie geeft van de api. Daarmee bedoel ik dat je ziet dat dit versie een is en dat de api iets doet met adressen in de Benelux. Ook het beginstuk van de api na de https geeft aan dat deze api van PostNL is. Deze bestaat uit een stuk protocol, subdomein en resource. Maar op een andere manier opgebouwd.
Je hebt als organisatie de vrijheid om zelf de naamgeving te kiezen, PostNL doet eerst de versie en dan de api-naam (address) en resource (Benelux). Een collega van mij had nog opmerkingen op de naam die in het enkelvoud is gesteld en in het meervoud zou moeten staan, collecties zijn altijd meervoud. Er is ook een REST Maturity Model ontwikkeld, zie deze post van Martin Fowler.
Documentatie en Open API
Welke parameters noodzakelijk zijn hangt af van de manier waarop de api ontwikkeld is. Van de PostNL-api hierboven weten we niet welke http verbs het ondersteunt en of er (en welke) parameters moeten worden meegestuurd.
Hiervoor heb je de documentatie nodig waarin je kunt zien wat er moet worden meegegeven en op welke manier. Een belangrijk onderdeel van de documentatie is de zogenaamde OpenAPI-specificatie. Hierin kun je bijvoorbeeld definiëren wat het schema is van de objecten die je kunt meesturen in een request, of kunt verwachten in een respons. Je kunt ook het formaat van de parameters in het resource pad definiëren (er kan nog veel meer, maar dat voert te ver voor dit artikel).
Dit kan je ook gebruiken om de request en respons at te dwingen. Aan de request-kant alleen maar de waarden toe te staan die je gedefinieerd, zoals een Burgerservicenummer dat maximaal negen cijfers bevat. Maar ook de response kan gevalideerd worden om te zorgen dat alleen responses die voldoen aan het schema worden terug gegeven. Beide zijn beveiligingsmechanismen van een apil. Schemavalidatie zorgt ervoor dat wat je definieert in het schema wordt afgedwongen, bij een afwijking wordt de API Request of Response niet doorgelaten.
Import en export
OpenAPI is eigenlijk de portable definitie van de api. Dit document kan worden gebruikt om de api te ex- en importeren in een API Management oplossing maar ook bijvoorbeeld in Postman waarmee api’s kunnen worden getest.
Daarnaast is echte documentatie, in meer proza de uitleg, aanroep, antwoorden en randvoorwaarden van de api die met een gebruiker moeten worden gedeeld.
Naast de informatie die nodig is om de api te Laten werken, zoals bijvoorbeeld een huisnummer of een adres in het geval van PostNL is er vaak ook nog een speciale key noodzakelijk waar mee een organisatie in staat is om de toegang tot de api te reguleren. Dat wil zeggen dat zonder deze key of sleutel (vaak een combinatie van letters of cijfers), is het niet mogelijk is om de api aan te roepen. Dit kan met het verdienmodel te maken hebben, zoals bij PostNL maar het heeft ook een gebruiker management rol in het bieden van toegang met bepaalde randvoorwaarden zoals een maximaal aantal aanroepen per periode per key.
Een foute, of niet actieve of ontbrekende sleutel zorg ervoor dat de API niet wordt uitgevoerd maar dat er een foutmelding wordt gegeven terug naar de gebruiker. Op deze manier kan de api gebruikt worden in een businessmodel waarbij geld wordt gevraagd wordt het gebruik van de api, eventueel in een zogenaamde freemium constructie. In het volgende artikel zal ik meer en dieper ingaan op dit onderwerp.
CRUD
Kijkend naar de 4 genoemde methods (GET POST PUT DELETE) komen deze grofweg overeen met de CRUD-set (Create, Read, Update en Delete) die we uit de database wereld kennen. Een POST is een CREATE, een GET is een READ, een PUT is een UPDATE en DELETE is natuurlijk DELETE. Waarbij ook geldt dat er soms meerdere manieren zijn om iets te bereiken. De PostNL-api gebruikt een POST (met een payload) om de systemen van PostNL te bevragen, RijksStudio (zie eerder voorbeeld en deel twee), de online-collectie-omgeving van het Rijksmuseum, gebruikt een GET met parameters in de URL om informatie uit de collectie op te halen. Beide kunnen en hebben voor- en nadelen
Er zijn trouwens meer HTTP methods dan de 4 die ik genoemd heb maar voor dit artikel is dit eigenlijk wel voldoende. Als je verder wilt lezen: er zijn voldoende artikelen onder andere op Wikipedia maar ook op W3SCHOOLS die meer informatie geven over de standaard protocollen van api’s maar ook In het bredere verband het internet en de gebruikte technologie.
In deel twee gaan we kijken op welke manier we api s kunnen aanroepen en gebruiken aan de hand van een aantal voorbeelden.
Auteur Rob Blaauboer is head of Training Services & Integration Consultant bij Yenlo.
