De anatomie van een API-aanroep

U heeft de term API (Application Program Interface) waarschijnlijk al meer dan een paar keer gehoord, maar begrijpt u goed wat een API is, wat het doet en hoe het werkt? In dit artikel ontleden we de term en onderzoeken we de vele verschillende aspecten van een API-aanroep.

Wat is een API?

Een API is software die communiceert met andere software en meestal een soort service aanbiedt. Een eenvoudig voorbeeld is een applicatie die postcodes regristreerd en vervolgens informatie van steden en provincies retourneert. De API-client (de gebruiker) vraagt informatie op van de server door de postcode als parameter in te voeren. De server accepteert de aanroep en stuurt de gevraagde gegevens terug.

Een API staat voor efficiëntie

Stelt u zich voor dat u hoofdpijn heeft. Om uw hoofdpijn te stoppen heeft u een pijnstiller nodig. U weet dat anderen pijnstillers hebben ontwikkeld die u daarbij kunnen helpen, maar in plaats daarvan moet u uw eigen versie van het medicijn maken. Zinloos, toch? Waarom al die tijd en moeite besteden aan het maken van uw eigen versie van een medicijn, terwijl zoveel anderen het al gedaan hebben? Ontwikkeling van software zonder API’s is vergelijkbaar daarmee.

Het probleem met delen of hergebruiken heeft softwareontwikkeling langere tijd geplaagd. Waarom zou een ontwikkelaar elke keer een nieuw postcodeprogramma moeten schrijven als het postkantoor er een gratis aanbiedt? Door gebruik te maken van een API hoeft de ontwikkelaar de applicatie niet te schrijven en ook niet elke keer te updaten als er een verandering in het postcodesysteem is. Omdat de ontwikkelaar de code niet hoeft te schrijven of te onderhouden, kunnen ze gelijk werken aan de code die uniek is voor hun applicatie.

API-implementatie

Hoe een uitgever kiest voor de implementatie van een API doet er niet aan toe. Dat klopt! Het kan de client niet schelen wat er buiten de interface gebeurt. Als u een kwartje in een kauwgombalmachine stopt, maakt het uit hoe de machine de kauwgombal opbrengt? Waarschijnlijk niet zo lang als u de kauwgombal ontvangt. De coderingstalen, databases en besturingssystemen die de API gebruikt, maakt de client niet uit – dat is het mooie van een API. Wat wel van belang is, is de interface.

Breek de interface niet

De systemen achter de interface kunnen volledig veranderen, maar de interface moet hetzelfde blijven. Eenmaal gepubliceerd, is de uitgever voorzichtig met het toevoegen van optionele parameters aan een interface. Veranderingen aan de vereiste parameters van een API-aanroep “breken” de interface. Bijvoorbeeld, als de postcode API’s interface in eerste instantie 5 cijfers voor een postcode nodig had, zal een extensie van 4 additionele cijfers de interface breken. Door deze verandering in de interface werkt elke applicatie die de oude interface gebruikte nu niet meer. Om dit probleem op te lossen kan de API-uitgever verschillende dingen doen:

• accepteer de vier-cijferige parameter met behulp van een optionele parameter.
• accepteer zowel vijf als negencijferige postcodes die de veranderingen achter de schermen kunnen afhandelen.
• de API uitbreiden met een nieuwe aanroep die een negen-cijferige look-up optie neemt en de originele API-aanroep met rust laat.

Een van de belangrijkste tools die u kunt hebben voor alle API’s is de API-documentatie. De documentatie is de sleutel tot het begrijpen van de interface. De uitgever kan statische API documentatie leveren (bekijk Uptrends’ MonitorCheck API statische documentatie) of interactieve documentatie in een product zoals Swagger (bekijk Uptrends’ API in Swagger). We komen terug op Swagger, maar de twee belangrijkste dingen om hier op te merken is dat u ten eerste altijd begint met de documentatie van de API en ten tweede, u deze dichtbij houdt voor referentie bij het coderen en het oplossen van problemen met de API.

Soorten API’s

API’s zijn er in allerlei soorten, afhankelijk van hun doel. Om het simpel te houden, kijken wij naar slechts twee API-groepen: webservices en alle andere.

Libraries, frameworks, en externe API’s

Ook wel broncode-API’s genoemd, ontwikkelaars gebruiken deze API’s binnen hun broncode om veel routinematige taken uit te voeren. Zo is een ODBC (open database connectivity) een API die een verbinding maakt tussen de applicatie en het database management systeem. De API beheert de interactie tussen de twee systemen, ongeacht het databasetype, besturingssysteem of locatie, zolang de database maar OBDC-conform is (leer meer over de verschillende soorten API’s).

API’s zoals API-libraries en -frameworks zorgen om verschillende redenen voor meer robuuste software en elektronica:

• Bemoedigt hergebruik van code
• Versnelt het ontwikkelingsproces
• Toelaten van het delen van bronbestanden. Bijvoorbeeld: een app op uw telefoon krijgt toegang tot locatiediensten met behulp van een API.

De API’s hebben het web en het Internet of Things gerevolutioneerd.

Webservice API’s

Webservices zijn API’s die taken uitvoeren via het internet. Bijna elke interactie die u online uitvoert maakt gebruik van één of meer webservices zoals:

• controleren op beschikbaarheid van reserveringen
• verwerken van creditcardtransacties
• Ophalen van actuele productinformatie uit de catalogus van leveranciers
• Uploaden/downloaden van afbeeldingen van sociale media
• Ontvangen van aanwijzingen van een navigatie app

De lijst gaat maar door en bevat veel functionaliteiten waar wij normaliter nooit aan denken. Bijvoorbeeld, statusupdates van uw smart devices, het navigatiesysteem van uw auto dat contact opneemt met Google Maps om actuele verkeerscondities te ontvangen (én versturen) en uw smart TV die toegang heeft tot de API van een streaming-service zoals Netflix.

Het ontleden van een webservice API-aanroep

Meestal gebruiken webservices de REST API (Representational State Transfer Application Program Interface) architectuurstijl. Een webservice die aan de REST API-stijl conformeert staat bekend als “RESTful”. REST dicteert geen taal of besturingssysteem, maar definieert alleen de design-principes waaraan een API moet voldoen om zichzelf RESTful te verklaren. Leer meer over RESTful APIs. De voorbeelden die volgen gebruiken een RESTful architectuurstijl.

Restful API’s gebruiken HTTP

RESTful APIs communiceren via HTTP/HTTPS op dezelfde manier als webbrowsers en een API-aanroep ziet er net zo uit als de URL om een webpagina te openen. Bijvoorbeeld, de aanroep naar Uptrends’ API om de volledige lijst van controlepunten en hun IP adressen te ontvangen is

https://api.uptrends.com/v4/Checkpoint

De URL om dezelfde gegevens te bekijken als een webpagina is

https://www.uptrends.com/checkpoints

Dat laatste voorbeeld resulteert in een webpagina, het eerste voorbeeld geeft een JavaScript Object Notation (JSON) of XML resultaat.

De HTTP-werkwoorden

De HTTP methodes of zogenaamde werkwoorden definiëren de benodigde acties. Hoewel u meer HTTP-request methodes kunt vinden, richten wij ons op vijf van de meest gebruikte methodes.

• GET
  De GET-verzoek methode haalt iets op van een bronbestand. Bijvoorbeeld, in het Checkpoint voorbeeld hierboven beschreven resulteert de API-aanroep in een lijst. Het kan echter ook een bestand, status, script of een ander digitaal bronbestand aanvragen.
• POST
  De POST-verzoek methode stuurt gegevens (en bestanden) naar het bronbestand. Bijvoorbeeld, een POST kan de bron opdracht geven om veel dingen te doen zoals een winkelwagen bijwerken, een account aanmaken, een reservering maken of social media updaten.
• PUT
  De PUT-verzoek methode is vergelijkbaar met de POST-methode omdat het verzoekt om het bronbestand te laten updaten of aan te maken. Het repliceren van een POST-verzoek doet echter helemaal niets, wat wil zeggen dat het idempotent is. Bij een POST is het bijvoorbeeld mogelijk dat het verzoek twee keer plaatsvindt wanneer een gebruiker een tweede keer op een submit-knop klikt. Door gebruik te maken van PUT kunt u dubbele klantorders voorkomen. Een PUT vereist dat het verzoek een URI (Uniform Resource Identifier) bevat, die op unieke wijze de resource identificeert die moet worden bijgewerkt. Als de resource al bestaat, maakt PUT de aanpassingen of als de resource nog niet bestaat, maakt PUT het object aan met die URI.
• PATCH
  Een PATCH is een gedeeltelijke wijziging of update van een bronbestand. Met een PUT of een POST verstuurt u elke keer de gehele resource, maar met een PATCH kunt u alleen de updates versturen.
• DELETE
  Net zoals het klinkt, een DELETE-verzoek verwijdert het bronbestand compleet. De server bepaalt hoe hij het DELETE-verzoek afhandelt en mag het bronbestand niet eigenhandig verwijderen.

HTTP-verzoek en respons

Zoals u waarschijnlijk al weet, een HTTP-verzoek is wanneer de client iets opvraagt van de server en de HTTP-respons is het antwoord dat terug komt van de host. De respons kan gegevens bevatten of alleen een resultaatcode. Zowel het verzoek als respons maken gebruik van de volgende format:

• Request Line
  De Request Line van de client specificeert de HTTP actie, de aanvraag van URI en de HTTP-versie. De respons heeft ook een “Request Line” maar deze Request Line bevat de HTTP-versie en de responscode.
• Headers
  HTTP gebruikt headers om extra informatie door te geven met behulp van een naam/waarde-paar. Het verzoek kan vele header-kolommen bezitten, zoals host, datum/tijd, verbindingsinformatie, informatie over het type inhoud, de grootte van de inhoud en de cache-instellingen.
• Lege lijn
  Een lege regel betekent het einde van de teksten van de header en het begin van de berichttekst.
• Message-instantie
  GET- en DELETE-verzoeken hebben geen optionele berichttekst nodig, maar in andere verzoeken bevat de berichttekst gegevens (indien aanwezig) die de server of client nodig heeft.

Laten we eens kijken naar een paar voorbeelden:

Sample verzoek

Het volgende verzoek is voor Uptrends’ checkpoint API. Zoals u kunt zien in de code hieronder, eerst is er de aanvraagregel met het soort methode, URI, en de protocolversie. De tweede regel, de ‘host header’, geeft de domeinnaam voor de server weer. De derde regel, de ‘accept header’, zegt tegen de API om te antwoorden in JSON code. De vierde regel is de ‘authorization header’ die de gecodeerde basis authenticatie details weergeeft.

GET /v4/checkpoint/202 HTTP1.1
Host: api.uptrends.com
Accept: application/json
Authorization: Basic bWjIxOEBNd2ljajb206MRnNjkzNAGFlbEB1cHRyZW5kcy5==

Sample respons

De eerste regel in de API-respons is de protocolversie en de resultaatcode. De headers in de respons geeft de browser informatie over de respons zoals hoe lang de inhoud in de cache kan blijven, type inhoud, datum/tijd en de lengte van de inhoud. Na de headers staat een lege regel gevolgd door de berichttekst. De berichttekst bevat JSON-code (zoals aangegeven in de aanvraag), maar is ook in XML beschikbaar.

HTTP/1.1 200 OK
access-control-expose-headers: Request-Context
cache-control: no-cache
content-length: 63823
content-type: application/json
date: Thu, 03 Sep 2020 20:41:47 GMT
expires: -1
pragma: no-cache
referrer-policy: same-origin
request-context: appId=cid-v1:fa5a4436-5708-4a19-90fb-5e2623304195

{
"Data": {
"Id": 202,
"Type": "Checkpoint",
"Attributes": {
"CheckpointName": "Aalsmeer",
"Code": "AAL1",
"Ipv4Addresses": [
"213.214.121.213",
"185.113.196.214"
],
"IpV6Addresses": [
{
"IpAddress": "2a02:2858:201:4e::5",
"IsNative": true
},
{
"IpAddress": "2a02:2858:401:1::214",
"IsNative": true
}
],
"IsPrimaryCheckpoint": true,
"SupportsIpv6": true,
"HasHighAvailability": false
},
"Links": {
"Self": "/Checkpoint/221"
}
},
"Links": {
"Self": "/Checkpoint/221"
}
}

In het bovenstaande voorbeeld wordt informatie gevraagd over één specifiek controlestation. Een eerdere aanroep met een andere URI heeft echter al de controlestation-ID opgehaald in dit voorbeeld. Sommige API-aanroepen staan op zichzelf, maar veel oproepen maken deel uit van een grotere API-uitwisseling.

Tools voor het testen van API-oproepen

Er zijn veel gratis en betaalde tools beschikbaar die u in staat stellen om API-aanroepen te ontwikkelen en te testen. Twee populaire tools zijn cURL en Swagger UI. Een andere populaire tool die wij kort willen benoemen is Postman.

cURL

cURL is waarschijnlijk de meest gebruikte tool. De “c” staat voor Command Line (opdrachtpromnpt) en het URL-gedeelte staat voor ‘Universal Resource Locator’. De tool maakt het mogelijk om gegevens te verzenden en te ontvangen vanaf de opdrachtprompt en HTTP is slechts één van de vele ondersteunde protocollen.

Waarschijnlijk heeft u cURL al op uw computer geïnstalleerd (als u gebruik maakt van Unix of een Mac is de tool al voorgeïnstalleerd). Om erachter te komen of uw Windows apparaat cURL heeft geïnstalleerd, kunt u een snelle test doen.

• Open het opdrachtprompt-venster (u kunt “CMD” in het zoekvenster typen om cmd.exe te vinden).
• Type curl https://www.uptrends.com op de opdrachtprompt.
• Druk op Enter.

Het resultaat (zie onderstaande figuur) is de HTML code van de Uptrends websites. Door gebruik te maken van de cURL-notatie kunt u headers toevoegen aan uw API-aanroepen. Leer meer over het gebruik van cURL en download cURL van de officiële website. U kunt ook het gratis e-boek downloaden; Everything curl.

Test API-aanroepen met behulp van Swagger

Swagger is een visuele documentatietool waarmee ontwikkelaars en gebruikers direct met uw API kunnen communiceren zonder dat er een infrastructuur aanwezig is. Als de API die u overweegt in gebruik te nemen een OpenAPI-specificatie heeft, kunt u gelijk van start. Uptrends heeft een OpenAPI Specificatie setup voor versie 4 van de API om gebruik van te maken als u een actief Uptrends account heeft.

Hoe maak ik gebruik van Uptrends’ OpenAPI Specificatie?

Als u een Uptrends log-in heeft, kunt u Uptrends’ Swagger pagina gebruiken om te communiceren met Uptrends’ API. In de volgende sectie doen we twee dingen: Laten zien hoe u een API-aanroep kunt uitvoeren met behulp van Swagger en u uw API-gebruikersnaam en wachtwoord kunt ontvangen.

Het eerste wat u moet doen is uw API-gegevens ophalen.

1. Ga naar Uptrends API v4 Swagger-documentatie.
2. Scroll naar beneden naar Register en klik om uit te breiden. U zult onderweg meer aanroepen zien, maar ga door met Registreren. U kunt altijd later met de anderen experimenteren.
   
3. Klik op de groene balk om de API-aanroepdocumentatie te bekijken.
4. Klik op Try it out om toegang te krijgen tot de Execute knop.
   
5. Klik op Execute.
6. Als u uw Uptrends-gegevens gebruikt, vult u het aanmeldingsformulier in het pop-up venster in.
7. Klik op Sign in.
8. Noteer de Gebruikersnaam en Wachtwoord in de responstekst. Deze heb je nodig om toegang te krijgen tot de API.
   
9. Scroll naar de top van de Swagger webpagina.
10. Klik op de groene Authorize knop.
11. Gebruik de gebruikersnaam en het wachtwoord die in de reponstekst zijn teruggekomen om de velden in te vullen (u hoeft alleen het bovenste gedeelte in te vullen).
    
12. Klik op Authorize.
13. Klik op Close.

Als u niet bent ingelogd, krijg u authenticatiefouten op uw API-aanroeppogingen. Speel met de verschillende API-aanroepen (het is waarschijnlijk het beste om vast te houden aan GET-verzoeken). Let wel op de cURL-syntax die gebruikt wordt om de aanroep te doen (zie onderstaand figuur). Swagger onderhoudt uw inloggegevens met een gecodeerde authorisatie headerwaarde.

Authorizatie header codering

Als u een Uptrends API gebruiker bent en gebruikt andere middelen (zoals scripts) om met de API te communiceren, kan het zijn dat u uw API-gegevens moet coderen. Om uw referenties te coderen, maak gebruik van base64 codering om de gebruikersnaam en het wachtwoord te scheiden met een dubbele punt.

Bijvoorbeeld, de gebruikersnaam en het wachtwoord

7341223ce90947cda53a66f67481908a:ipbI6+6wUXxlCYSTBUaCuuUyjTQYfNjM

wordt

NzM0MTIyM2NlOTA5NDdjZGE1M2E2NmY2NzQ4MTkwOGE6aXBiSTYrNndVWHhsQ1lTVEJVYUN1dVV5alRRWWZOak0=

met basis64-codering en behulp van deze gratis online tool.

Conclusie

Hopelijk heeft u na afloop een beter begrip van webservices en hoe ze werken. We raden u aan om de Uptrends API te blijven verkennen met behulp van Swagger, en u zult merken dat deze informatie ook van pas komt bij het opzetten van Multi-Step API Monitoring. Als u vragen heeft over de API, raden we aan om onze Knowledge Base te verkennen of een van onze ondersteuningshelden te raadplegen.