Aan de slag met Python HTTP-requests voor REST-API’s

GET- en POST-requests maken met de Python requests-module

Haast? Dit is de Python-syntax voor een simpele GET- en POST-request:

1. GET-request

import requests

# The API endpoint
url = "https://jsonplaceholder.typicode.com/posts/1"

# A GET request to the API
response = requests.get(url)

# Print the response
print(response.json())

2. POST-request

import requests

# The API endpoint
url = "https://jsonplaceholder.typicode.com/posts"

# Data to be sent
data = {
    "userID": 1,
    "title": "Making a POST request",
    "body": "This is the data we created."
}

# A POST request to the API
response = requests.post(url, json=data)

# Print the response
print(response.json())

REST-API’s en hun HTTP-basis begrijpen

We hebben vastgesteld dat API’s softwarebemiddelaars zijn. Je kunt ze ook zien als een soort software-interface die andere applicaties toegang geeft tot specifieke data en methoden. 

Een van de populairste architecturen om API’s te bouwen is het REpresentational State Transfer (REST)-patroon. Het REST-ontwerp maakt het mogelijk dat client en server onafhankelijk van elkaar worden geïmplementeerd zonder elkaar te kennen. Dit betekent dat code aan beide kanten kan worden gewijzigd zonder je zorgen te maken over de impact op de andere kant. 

REST-API’s volgen daarom een set richtlijnen die communicatie tussen software vereenvoudigen en zo het proces van data benaderen overzichtelijker en logischer maken. Maak je geen zorgen als je deze richtlijnen niet kent; je hebt ze niet nodig om te beginnen – wat je wél moet weten is hoe data wordt blootgesteld door REST-services. 

Data van REST-webservices worden via een publieke URL op internet aangeboden, die je kunt benaderen door een HTTP-request te sturen.  

Overzicht van HTTP-requestmethoden

Terug naar onze restaurantanalogie: om eten te bestellen in een restaurant komt de ober naar je toe en zeg je wat je wilt. De ober geeft je verzoek door aan de chef, die het gerecht maakt en het via de ober weer bij je laat bezorgen. Met andere woorden: de chef kookt je maaltijd pas nadat je je verzoek hebt gedaan. 

REST-API’s werken hetzelfde: ze wachten op HTTP-requestmethoden voordat ze actie ondernemen. HTTP definieert een set requestmethoden die de API vertellen welke bewerkingen voor een bepaalde resource moeten worden uitgevoerd. Het specificeert hoe je moet interacteren met de resources op de opgegeven endpoint. 

Er zijn verschillende HTTP-methoden, maar vijf worden het meest gebruikt met REST-API’s: 

De kans is groot dat je in data-analyse en data science vooral GET-requests zult uitvoeren. Dat komt omdat dit de methode is die nodig is om bepaalde datasets te benaderen. Leer hier meer over in DataCamp’s Intermediate Importing Data in Python-cursus.

Wanneer je een request naar een webserver doet, retourneert de API een response. Aan de response zit een HTTP-statuscode gekoppeld. Het doel van de statuscode is extra informatie te geven over de response, zodat de client weet welk type antwoord is ontvangen.

Wat zijn API-endpoints?

Een URL bepaalt met welke data je op een webserver interageert. Net zoals een webpagina-URL aan één pagina is gekoppeld, is een endpoint-URL gekoppeld aan specifieke resources binnen een API. Een endpoint kun je dus zien als een digitale locatie waar een API vragen ontvangt over een bepaalde resource op zijn server — zie het als het andere uiteinde van een communicatiekanaal. 

Voor meer context: REST-API’s stellen een set publieke URL’s bloot die door clientapplicaties kunnen worden aangeroepen om de resources van de webservice te benaderen. De publieke URL’s die door de REST-API worden aangeboden, noemen we “endpoints”.

Python gebruiken om HTTP-requests te maken

De Python-requests-module stelt ontwikkelaars in staat om code te schrijven om met REST-API’s te interacteren. Je kunt er HTTP-requests mee versturen in Python zonder je te hoeven bekommeren om de complexiteit die daar normaliter bij komt kijken (zoals handmatig querystrings aan URL’s toevoegen, PUT- en POST-data form-encoden, enz.). 

Hoewel het de de facto standaard is voor het maken van HTTP-requests in Python, maakt de requests-module geen deel uit van de standaardbibliotheek van Python – je moet hem installeren. 

De eenvoudigste manier om de requests-module te installeren is met pip: 

python -m pip install requests

Het is altijd aan te raden om de Python-pakketten die je voor verschillende projecten nodig hebt te beheren met virtuele omgevingen; zo beïnvloeden pakketten voor het ene project niet de systeemsjablonen of tools in andere projecten omdat ze geïsoleerd zijn – in plaats van globaal geïnstalleerd. 

Nu we de requests-module hebben geïnstalleerd, gaan we kijken hoe het werkt. Volg mee met de code in dit DataLab-werkboek. 

Een GET-request maken in Python

We hebben al vastgesteld dat GET een van de meest voorkomende HTTP-requestmethoden is die je tegenkomt bij het werken met REST-API’s. Het stelt jou (de client) in staat om data op te halen van webservers. 

Belangrijk om te weten: GET is een read-only-operatie, wat betekent dat het alleen geschikt is om bestaande resources te benaderen en niet om ze te wijzigen. 

Om te laten zien hoe de requests-module werkt, gebruiken we JSONPlaceholder, een vrij beschikbare nep-API voor testen en prototyping. 

import requests

# The API endpoint
url = "https://jsonplaceholder.typicode.com/posts/1"

# A GET request to the API
response = requests.get(url)

# Print the response
response_json = response.json()
print(response_json)

"""
{'userId': 1, 'id': 1, 'title': 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit', 'body': 'quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nostrum rerum est autem sunt rem eveniet architecto'}
"""

In de bovenstaande code deden we het volgende: 

1. De API-endpoint gedefinieerd waarvan we data willen ophalen.

2. De methode requests.get(url) gebruikt om de data van de gedefinieerde endpoint op te halen. 

3. De methode response.json() gebruikt om de response-data in een dictionary-object op te slaan; let op: dit werkt alleen omdat het resultaat in JSON-formaat is geschreven – anders was er een fout opgetreden.   

4. Als laatste stap de JSON-responsedata geprint. 

We kunnen ook de statuscode controleren die door de API is teruggegeven, zo: 

# Print status code from original response (not JSON)
print(response.status_code)

"""
200
"""

Je kunt ook argumenten meegeven aan een Python-GET-request. Daarvoor moeten we de code hierboven een beetje aanpassen. Zo ziet de nieuwe code eruit:

# The API endpoint
url = "https://jsonplaceholder.typicode.com/posts/"

# Adding a payload
payload = {"id": [1, 2, 3], "userId":1}

# A get request to the API
response = requests.get(url, params=payload)

# Print the response
response_json = response.json()

for i in response_json:
    print(i, "\n")

"""
{'userId': 1, 'id': 1, 'title': 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit', 'body': 'quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nostrum rerum est autem sunt rem eveniet architecto'}

{'userId': 1, 'id': 2, 'title': 'qui est esse', 'body': 'est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla'}

{'userId': 1, 'id': 3, 'title': 'ea molestias quasi exercitationem repellat qui ipsa sit aut', 'body': 'et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut ad\nvoluptatem doloribus vel accusantium quis pariatur\nmolestiae porro eius odio et labore et velit aut'}
"""

Dit deden we anders: 

1. De API-endpoint aangepast. Let op dat er niet langer een 1 aan het einde staat. 

2. De payload gedefinieerd in een dictionary.  

3. De payload doorgegeven aan het param-argument van de methode requests.get(). 

4. Dit leverde een list-object op, dus we hebben door de lijst geloopt en elk item op een nieuwe regel geprint. 

Een POST-request maken in Python

GET-requests laten je data ophalen; met POST-requests kun je nieuwe data aanmaken. Laten we kijken hoe we nieuwe data kunnen aanmaken op de JSONPlaceholder-server.

# Define new data to create
new_data = {
    "userID": 1,
    "id": 1,
    "title": "Making a POST request",
    "body": "This is the data we created."
}

# The API endpoint to communicate with
url_post = "https://jsonplaceholder.typicode.com/posts"

# A POST request to tthe API
post_response = requests.post(url_post, json=new_data)

# Print the response
post_response_json = post_response.json()
print(post_response_json)

"""
{'userID': 1, 'id': 101, 'title': 'Making a POST request', 'body': 'This is the data we created.'}
"""

In de bovenstaande code voerden we het volgende uit: 

1. Een nieuwe resource gemaakt die we aan de JSONPlaceholder-API wilden toevoegen.

2. De endpoint gedefinieerd waar we de nieuwe data naartoe willen POSTen.

3. Een POST-request verstuurd met de methode requests.post(). Let op dat de parameter json is gezet in de post()-methode; dit doen we om de API expliciet te vertellen dat we een JSON-object naar de opgegeven URL sturen. 

4. De methode response.json() gebruikt om de response-data in een dictionary-object op te slaan.

5. Als laatste stap de JSON-responsedata geprint. 

Maar wacht!

Voordat je de volgende code leest, neem 20 seconden om te bedenken welke statuscode de API zal teruggeven. 

Onthoud: deze keer hebben we een nieuwe resource gemaakt in plaats van die simpelweg op te halen. 

Oké, daar komt-ie… 

# Print status code from original response (not JSON)
print(post_response.status_code)

"""
201
"""

Geavanceerde onderwerpen rond Python HTTP-requests

HTTP-requests maken met Python is meestal eenvoudig; toch heb je soms een geavanceerdere setup nodig of loop je onvermijdelijk tegen problemen aan. Hier zijn enkele uitdagingen die je kunt tegenkomen en hoe je ze oplost. 

HTTP-requests authenticeren

Tot nu toe waren onze interacties met de REST-API vrij eenvoudig. De JSONPlaceholder-API vereist geen authenticatie om ermee te kunnen werken. Er zijn echter genoeg situaties waarin een REST-API authenticatie vereist voordat toegang wordt verleend tot specifieke endpoints – zeker wanneer je met gevoelige data werkt. 

Als je bijvoorbeeld integraties wilt bouwen, data wilt ophalen en je workflows op GitHub wilt automatiseren, kan dat met de GitHub REST-API. Er zijn echter veel operaties in de GitHub REST-API die authenticatie vereisen, zoals het ophalen van publieke en private informatie over geauthenticeerde gebruikers. 

Hier is een eenvoudige aanpak met de Python requests-module: 

from requests.auth import HTTPBasicAuth

private_url = "https://api.github.com/user"
github_username = "username"
token = "token"

private_url_response = requests.get(
    url=private_url,
    auth=HTTPBasicAuth(github_username, token)
)

private_url_response.status_code

"""
200
"""

In de bovenstaande code hebben we:

1. Het HTTPBasicAuth-object geïmporteerd uit requests.auth. Dit object voegt HTTP basic-authenticatie toe aan het gegeven requestobject — het is in essentie hetzelfde als je gebruikersnaam en wachtwoord intoetsen op een website. 

2. De private URL-endpoint gedefinieerd die we willen benaderen.

3. Een variabele met een GitHub-gebruikersnaam geïnstantieerd – we hebben de gebruikersnaam geanonimiseerd.

4. Een variabele geïnstantieerd met een GitHub-persoonlijke access token voor authenticatie.  

5. Data opgehaald van onze endpoint en opgeslagen in de variabele private_url_response. 

6. De statuscode weergegeven.  

HTTP-requestfouten afhandelen

Er zijn situaties waarin requests naar een API niet gaan zoals verwacht. Er kunnen verschillende factoren meespelen aan de client- of serverkant. Ongeacht de oorzaak is de uitkomst hetzelfde: het request faalt. 

Bij het gebruik van REST-API’s is het altijd een goed idee om je code robuust te maken. Maar voordat je robuuste code kunt schrijven, moet je begrijpen hoe je de gerapporteerde fouten beheert wanneer dingen niet volgens plan gaan.  

Voor deze demonstratie gaan we terug naar de JSONPlaceholder-API. We schrijven eerst wat code en leggen daarna uit wat er gebeurt.  

# A deliberate typo is made in the endpoint "postz" instead of "posts"
url = "https://jsonplaceholder.typicode.com/postz"

# Attempt to GET data from provided endpoint
try:
    response = requests.get(url)
    response.raise_for_status()
# If the request fails (404) then print the error.
except requests.exceptions.HTTPError as error:
  print(error)

"""
404 Client Error: Not Found for url: https://jsonplaceholder.typicode.com/postz
"""

In de bovenstaande code: 

1. Hebben we de JSONPlaceholder-endpoint gedefinieerd waarvan we data willen ophalen, maar een opzettelijke typefout gemaakt in de URL – dit veroorzaakt een 404-fout. 

2. Hebben we Python’s ingebouwde exception handling gebruikt om fouten te tryen en te excepten (op te vangen) die optreden wanneer we de JSONPlaceholder-endpoint proberen te bezoeken. Let op: de methode raise_for_status() is wat een HTTPError-object teruggeeft wanneer er tijdens het proces een fout optreedt.

3. En tot slot hebben we de fout geprint die werd opgegooid. 

Hoewel we hier hebben laten zien hoe je 404-statuscodes afhandelt, kun je hetzelfde patroon gebruiken om elke HTTP-statuscode af te handelen. 

Omgaan met te veel redirects

HTTP-statuscodes in het 3xx-bereik geven aan dat de client is doorgestuurd en extra acties moet ondernemen om het request te voltooien. Dit kan soms leiden tot een oneindige redirect-lus.

De requests-module in Python biedt het object TooManyRedirects om dit probleem op te vangen, als volgt: 

"""
Note: The code here will not raise an error
but the structure is how you would hand a case where there
are multiple redirects
"""

url = "https://jsonplaceholder.typicode.com/posts"

try:
  response = requests.get(url)
  response.raise_for_status()
except requests.exceptions.TooManyRedirects as error:
  print(error)

Je kunt ook het maximum aantal redirects instellen als parameter van je HTTP-requestmethode: 

# Solution 2
url = "https://jsonplaceholder.typicode.com/posts"
session = requests.Session()
session.max_redirects = 3
response = session.get(url)

Een andere optie is om redirects volledig uit te schakelen: 

# Solution 3
url = "https://jsonplaceholder.typicode.com/posts"
session = requests.Session()
session.allow_redirects = False
response = session.get(url)

Verbindingsfouten bij HTTP-requests afhandelen

Dit zijn andere soorten fouten waar je tegenaan kunt lopen wanneer je requests naar een server verstuurt. Er zijn verschillende redenen waarom je geen response van de server ontvangt (bijv. DNS-fout, geweigerde verbinding, problemen met je internetverbinding, enz.), maar de uitkomst is hetzelfde: er treedt een verbindingsfout op. 

Je kunt het ConnectionError-exceptionobject van de requests-module gebruiken om deze problemen op te vangen en gepast af te handelen. 

Zo zou de code eruitzien:  

"""
Note: The code here will not raise an error
but the structure is how you would hand a case where there
is a connection error.
"""

url = "https://jsonplaceholder.typicode.com/posts"

try:
  response = requests.get(url)
except requests.ConnectionError as error:
  print(error)

Timeouts bij HTTP-requests afhandelen

Wanneer de API-server je verbinding accepteert maar je request niet binnen de toegestane tijd kan afronden, krijg je een “timeout error”.

We laten zien hoe je dit afhandelt door de parameter timeout in de methode requests.get() op een extreem klein getal te zetten; dit veroorzaakt een fout, en die handelen we af met het object requests.Timeout. 

url = "https://jsonplaceholder.typicode.com/posts"

try:
  response = requests.get(url, timeout=0.0001)
except requests.Timeout as error:
  print(error)

De eenvoudigste oplossing voor timeoutfouten is om langere timeouts in te stellen. Andere oplossingen zijn onder meer je requests optimaliseren, een retry-lus in je scripts opnemen of asynchrone API-calls uitvoeren – een techniek waarmee je software een mogelijk langlopende taak kan starten en ondertussen responsief blijft voor andere events, in plaats van te wachten tot de taak is voltooid.

Afsluiting

In deze tutorial bespraken we wat API’s zijn en verkenden we een veelgebruikte API-architectuur genaamd REST. We hebben ook gekeken naar HTTP-methoden en hoe we de Python-requests-bibliotheek kunnen gebruiken om met webservices te interacteren. 

Bekijk de volgende cursussen om je data science-skills te ontwikkelen: 

• Introduction to APIs in Python
• Streamlined Data Ingestion with Pandas 
• Analyzing Social Media Data in Python
• Intermediate Importing Data in Python