Wat is een API & hoe werkt een API? Simpele uitleg + voorbeeld

In dit blog gaan we uitgebreid in op wat een API is en hoe je ermee werkt. We zullen eerst de theorie uitleggen en daarna een uitgebreid voorbeeld uitwerken. In het voorbeeld werken we met programmeertaal Python. Je kunt met meer programmeertalen met APIs werken.

• Wat is een API?
• Wat kan ik met een API?
• Welke toepassingen zijn er?
• Voorbeeld: werken met een API met Python
• Overige request types
• API documentatie

Wat is een API?

API staat voor Application Programming Interface. Dat betekent applicatie programmerings interface.

Dit is een gestandaardiseerde en gestructureerde manier om met andere applicaties interactie te hebben.

Een voorbeeld

Denk aan het volgende voorbeeld:

• Je bedrijf werkt met een ERP-systeem
• Jij wilt data uitwisselen met het ERP-systeem over inkooporders
• Dat kun je handmatig doen, of misschien dat je rechtstreeks een database-query uit kunt voeren
  • Nadeel van handmatig is dat het niet geautomatiseerd is
  • Nadeel van een directe query is dat je fouten kunt maken, je bent op jezelf aangewezen
• Met een API geeft het ERP-systeem je standaard mogelijkheden. Dan kun je bijvoorbeeld op een standaard manier data van alle openstaande inkooporders opvragen

De algemene werking is onderstaand schematisch weergegeven:

1. Een gebruiker voert via een internet URL een verzoek (request) uit om data
2. De API ontvangt dit verzoek (request)
3. De API verwerkt dit verzoek en roept data op uit de database van de applicatie
4. De API ontvangt de data uit de database
5. De API stuurt antwoord (response) met de data naar de gebruiker

Wat kan ik met een API?

Een API is dus een standaard manier om interactie te hebben met een applicatie.

Je voert de opdrachten uit via een webadres (URL).

We hebben het nu gehad over het opvragen van data.

Dat is niet de enige mogelijkheid.

Met een API kun je vaak:

• Data opvragen (GET)
• Data toevoegen (POST)
• Data wijzigen (PUT)
• Data verwijderen (DEL)

De termen GET, POST, PUT en DEL zijn de technische termen.

Welke toepassingen zijn er?

APIs worden door veel moderne applicaties gebruikt. Bijna iedere applicatie die jij gebruikt heeft er inmiddels wel een. Dat kan een website (webapplicatie) zijn. Maar het kan ook een applicatie op een lokale server zijn (bijvoorbeeld een ERP systeem).

Denk bijvoorbeeld aan:

• CBS
• Exact ERP
• Rabobank
• WooCommerce webshop
• WordPress website
• ArcGIS
• Microsoft 365
• Etc.

Je kunt zelf ook een API maken voor je eigen applicatie. Lees meer over het maken van een eigen API in ons blog daarover.

Voorbeeld: werken met een API met Python

Een API is dus een standaard manier om interactie te hebben met een applicatie.

Met Python kun je hier gemakkelijk mee werken.

Hiervoor kun je het beste package Requests gebruiken.

Voorbeeld (stap 1): CBS dataset Nederlandse huizenprijzen

We gaan APIs met Python verkennen vanuit een voorbeeld.

• Hier halen we data op van de ontwikkeling van Nederlandse huizenprijzen over tijd
• Deze data halen we uit de CBS API (Centraal Bureau voor de Statistiek)

Voorbeeld (stap 2): CBS StatLine dataset

Deze data is te vinden op StatLine, het dataportaal van het CBS:

Voorbeeld (stap 3): CBS StatLine dataset detailpagina

Vervolgens vinden we daar de link naar de detailpagina waar de API details staan.

Hier vinden we uiteindelijk deze API URL

Voorbeeld (stap 4): CBS StatLine dataset in XML formaat in de browser

Wanneer je op de URL klikt zie je het volgende:

Dit is data in XML-formaat (Extensible Markup Language). Deze data bevat de details van de Nederlandse huizenprijzen.

Voorbeeld (stap 5): Data opvragen met een GET request

Met een GET request kan data uit een API opgevraagd worden.

We hebben inmiddels een API URL van de Nederlandse huizenprijzen van het CBS.

Deze data hebben we in XML-formaat in de browser bekeken.

Nu gaan we dit met Python doen.

Dit doen we onderstaand als volgt:

• We importeren package requests
• We maken constante API_URL_HOUSE_PRICES aan met de API URL van het CBS
• Met .get() voeren we een GET request uit. Dit om de data van de huizenprijzen op te halen. We slaan het resultaat op in variabele response.

import requests

API_URL_HOUSE_PRICES = 'https://opendata.cbs.nl/ODataFeed/odata/83625NED/TypedDataSet'

response = requests.get(url=API_URL_HOUSE_PRICES)

Voorbeeld (stap 6): De status van een request met .status_code

Wanneer je een request (verzoek) via het web (een URL) plaats, krijg je altijd een terugkoppeling.

Deze terugkoppeling is de status code: een gestandaardiseerde code van 3 cijfers die je iets vertelt over de status.

Voorbeelden zijn:

• 200: Succesvol
• 401: Geen toegang
• 404: Niet gevonden

Package requests laat ons dit ook gebruiken.

Hiervoor gebruiken we attribuut .status_code:

response.status_code

200

Je ziet 200, dit betekent een succesvol request (verzoek om informatie).

Voorbeeld (stap 7): De status van een request met .ok

Naast attribuut .status_code kunnen we ook attribuut .ok toepassen.

Dit geeft een boolean (True, False) terug.

response.ok

True

In dit geval vertelt True ons dat we een succesvol request hebben uitgevoerd.

Voorbeeld (stap 8): De inhoud van een request met .text

Met attribuut .text kan de inhoud van het request verkregen worden.

Dit is de werkelijk opgevraagde informatie / dataset.

response.text

Omdat de output hiervan erg groot is laten we een afbeelding van de output zien op deze pagina.

Je ziet dat dit de dataset in XML-formaat is.

Voorbeeld (stap 9): Headers van een request

Met de headers van een request kan algemene informatie over het request meegestuurd worden. Het wordt ook wel gebruikt voor authenticatie.

We verkregen de dataset in XML-formaat.

Dat is in de praktijk meestal niet wenselijk.

In de praktijk zul je met APIs vaak met data in JSON-formaat (JavaScript Object Notation) werken.

Door gebruik te maken van de headers kunnen we dit als opdracht in een request aangeven.

Dit doen we als volgt:

• We maken een dictionary headers aan, en benoemen hierin dat we json data willen gebruiken
• Dit vullen we in als parameter headers

import requests

API_URL_HOUSE_PRICES = 'https://opendata.cbs.nl/ODataFeed/odata/83625NED/TypedDataSet'

headers = {
    'accept': 'application/json'
}

response = requests.get(url=API_URL_HOUSE_PRICES, headers=headers)

response.ok

True

Hierbij is 'accept': 'application/json' erg standaard.

Dit zul je bij veel APIs zien terugkeren.

Het is ook altijd terug te vinden in de documentatie van een API.

Voorbeeld (stap 10): De inhoud van een request als JSON met .json()

Met methode .json() kan de inhoud van het request in JSON-formaat verkregen worden.

Dit wordt vaak gebruikt.

response.json()

Omdat de output wederom zeer groot is laten we weer een screenshot van de output zien op deze pagina.

Je ziet dat dit er gestructureerd uitziet.

Het lijkt sterk op een Python dictionary: key-value paren.

Voorbeeld (stap 11): De JSON data omzetten naar een Pandas DataFrame

We hebben een dataset met huizenprijzen over tijd.

Dit klinkt als data in een tabelvorm.

Hiervoor zou een Pandas DataFrame ideaal zijn.

Wanneer we naar de keys van de JSON data kijken zien we het volgende:

response.json().keys()

dict_keys(['odata.metadata', 'value', 'odata.nextLink'])

De werkelijke data van de huizenprijzen is aanwezig in key value.

Dit is een list van dictionaries.

Dit kunnen we als volgt omzetten naar een Pandas DataFrame:

import pandas as pd

json_data = response.json()['value']
df = pd.DataFrame(json_data)

df

Mooi, de data is nu handig beschikbaar als Pandas DataFrame.

Echter, we zien dat het precies 10.000 rijen zijn.

Dit komt doordat de CBS API niet meer 10.000 rijen per request teruggeeft. Het kan daarom soms handig zijn om data in batches op te halen.

Dit staat overigens netjes in de documentatie van de API.

In kolom RegioS zien we ook waarden zoals GM0332.

Dit zijn gemeentecodes.

Wij zijn nu echter alleen benieuwd naar de huizenprijzen van Nederland als geheel

Je herkent deze in kolom RegioS aan de waarden NL01.

Voorbeeld (stap 12): Query filters opgeven met params (parameters)

Met een query filter selecteer je specifieke data.

We hebben gezien dat we nu ook alle data ophalen voor iedere provincie.

Dat is niet wenselijk.

Dit kunnen we voorkomen door een query filter.

Hierdoor selecteer je specifieke informatie.

Zo'n query filter is op te geven met parameter params in een .get() request.

Dit doen we onderstaand als volgt:

• We maken variabele params aan (een dictionary)
• Hierin benoemen we 1 query filter. Waarden in kolom RegioS moeten beginnen met 'NL01'. Dit kun je vinden in de documentatie van de CBS API

import requests

api_url = 'https://opendata.cbs.nl/ODataFeed/odata/83625NED/TypedDataSet'

headers = {
    'accept': 'application/json'
}

params = {
    '$filter': "startswith(RegioS, 'NL01')",
}

response = requests.get(api_url, headers=headers, params=params)

response.ok

True

Wanneer we nu de JSON data omzetten naar een Pandas DataFrame zien we het volgende:

import pandas as pd

json_data = response.json()['value']
df = pd.DataFrame(json_data)

df

Mooi, we hebben nu alleen de data van Nederland als geheel.

Voorbeeld (stap 13): Omzetten naar grafiek

Nu de juiste data in tabelvorm staat is dit eenvoudig te tonen als grafiek:

%matplotlib inline

import matplotlib.pyplot as plt

# Add column year.
df['year'] = df['Perioden'].str[:4].astype(int)

# Create plot.
plt.style.use('seaborn')
fig, ax = plt.subplots(figsize=(8, 5))    
ax.plot(df['year'], df['GemiddeldeVerkoopprijs_1'])
ax.set_xlabel('Year')
ax.set_ylabel('Price (€)')
ax.set_title('Average house price in the Netherlands by year');

Dat geeft een mooi inzicht in de data.

Overige request types

We hebben kennisgemaakt met een GET request om informatie op te halen.

Dit deden we met het .get() request.

Naast GET bestaan ook de volgende request types:

• Data toevoegen (POST): .post()
• Data wijzigen (PUT): .put()
• Data verwijderen (DEL): .delete()

Deze requests werken vergelijkbaar als het .get() request.

Hier gaan we nu niet verder op in.

API documentatie

Bij het gebruik van een API is het erg belangrijk dat er goede documentatie beschikbaar is.

De documentatie moet uitleggen wat alle mogelijkheden zijn.

Dit ook het liefst aan de hand van enkele voorbeelden.

Veelgebruikte vormen van documentatie

Er zijn enkele veelgebruikte vormen van documentatie.

Dit is bijvoorbeeld:

• Swagger
• ReDoc

Dat ziet er bijvoorbeeld als volgt uit:

API documentatie vertelt je alle mogelijkheden van de API en hoe je deze gebruikt.

De CBS API documentatie is momenteel alleen beschikbaar in een PDF.

Wil je nog veel meer leren over met mogelijkheden met Python voor Data Science? Schrijf je dan in voor onze Python cursus voor data science, onze machine learning training, onze data science opleiding of onze data science bootcamp en leer met vertrouwen te programmeren en analyseren in Python. Nadat je een van onze trainingen hebt gevolgd kun je zelfstandig verder aan de slag. Je kunt ook altijd even contact opnemen als je een vraag hebt. Bij al deze trainingen is het mogelijk een zelfstudie add-on te selecteren waarin je meer leert over werken met APIs vanuit Python

Download één van onze opleidingsbrochures voor meer informatie