Eine REST-API mit Python und requests aufrufen: praktische Beispiele
So nutzen Sie die Bibliothek requests, um in Python Daten von einer REST-API zu lesen und an sie zu senden: GET und POST, JSON, Authentifizierung, Fehler und automatische Wiederholungen.
Viele Dienste, die wir täglich nutzen, von der Wettervorhersage bis zur Unternehmenssoftware, stellen ihre Daten über eine API bereit. Wer sie aus Python heraus nutzen kann, automatisiert damit eine Vielzahl von Aufgaben: Daten herunterladen, zwei Dienste synchronisieren, Inhalte veröffentlichen, Berichte erstellen.
In dieser Anleitung verwenden wir requests, die verbreitetste Bibliothek für diesen Zweck, mit Beispielen, die Sie sofort mit kostenlosen öffentlichen APIs ausprobieren können.
Was ist eine REST-API, kurz erklärt
Eine API (Application Programming Interface) ist ein Weg, über den ein Programm ein anderes um Daten oder Aktionen bitten kann. REST-APIs funktionieren über das Web, mit demselben Protokoll wie Websites: HTTP. Es gibt nur wenige Begriffe, die Sie kennen müssen:
- Endpunkt: die Adresse, an die die Anfrage geht, zum Beispiel
https://api.example.com/kunden. - Methode: die Art der Operation. Die wichtigsten sind
GET(lesen),POST(erstellen),PUToderPATCH(ändern) undDELETE(löschen). - JSON: das Textformat, in dem Daten meist ausgetauscht werden. In Python wird daraus ein Dictionary oder eine Liste.
- Statuscode: eine Zahl, die das Ergebnis angibt.
200und201bedeuten Erfolg;4xxsteht für einen Fehler in der Anfrage (zum Beispiel401nicht autorisiert,404nicht gefunden,429zu viele Anfragen);5xxfür ein Problem des Servers.
requests installieren
Wie immer arbeiten Sie am besten in einer virtuellen Umgebung. Bei aktiver Umgebung:
python -m pip install requests
Die erste GET-Anfrage: die Wettervorhersage
Wir verwenden Open-Meteo, einen kostenlosen Wetterdienst ohne Registrierung. Fragen wir das aktuelle Wetter in Mailand ab:
import requests
URL = "https://api.open-meteo.com/v1/forecast"
params = {
"latitude": 45.46,
"longitude": 9.19,
"current": "temperature_2m,wind_speed_10m",
"timezone": "auto",
}
response = requests.get(URL, params=params, timeout=10)
response.raise_for_status()
data = response.json()
current = data["current"]
print(f"Temperatur: {current['temperature_2m']} °C")
print(f"Wind: {current['wind_speed_10m']} km/h")
Die wichtigen Zeilen im Einzelnen:
params: requests hängt die Parameter im richtigen Format an die Adresse an und behandelt dabei auch Leerzeichen und Sonderzeichen. Sie müssen die URL nicht von Hand zusammensetzen.timeout=10: Antwortet der Server nicht innerhalb von 10 Sekunden, wird die Anfrage abgebrochen. Ohne Timeout kann ein Skript endlos hängen. Setzen Sie ihn immer.raise_for_status(): Zeigt der Statuscode einen Fehler an, wird eine Ausnahme ausgelöst, statt mit falschen Daten weiterzumachen.json(): wandelt die Antwort in ein Python-Dictionary um.
Ein praktischer Tipp: Wenn Sie mit einer neuen API arbeiten, geben Sie die vollständige Antwort mit print(data) aus, um ihre Struktur zu sehen, bevor Sie die gewünschten Felder herausziehen.
Daten mit einer POST-Anfrage senden
Um etwas zu erstellen, verwendet man die Methode POST. Um es gefahrlos auszuprobieren, nutzen wir JSONPlaceholder, einen Testdienst, der eine echte API simuliert, aber nichts speichert:
import requests
new_post = {
"title": "Test",
"body": "Testinhalt",
"userId": 1,
}
response = requests.post(
"https://jsonplaceholder.typicode.com/posts",
json=new_post,
timeout=10,
)
response.raise_for_status()
print(response.status_code) # 201: erstellt
print(response.json()) # die empfangenen Daten mit der vergebenen id
Der Parameter json= wandelt das Dictionary in JSON um und setzt automatisch den Header Content-Type: application/json. Das ist etwas anderes als data=, das die Daten wie ein Webformular sendet: Erwartet eine API JSON, verwenden Sie immer json=.
Authentifizierung mit einem Token
Private APIs verlangen, dass Sie sich ausweisen. Die gängigste Methode ist ein Token (oder API-Schlüssel), der in den Headern der Anfrage mitgeschickt wird:
import os
import requests
token = os.environ["API_TOKEN"]
headers = {
"Authorization": f"Bearer {token}",
"Accept": "application/json",
}
response = requests.get(
"https://api.example.com/v1/kunden",
headers=headers,
timeout=10,
)
Beachten Sie, dass der Token nicht im Code steht: Er wird aus einer Umgebungsvariablen gelesen. Das ist eine wichtige Sicherheitsregel: Landet der Code auf GitHub oder wird er weitergegeben, bleibt der Token privat. So setzen Sie die Variable vor dem Start des Skripts:
# Windows, Eingabeaufforderung
set API_TOKEN=ihr-token
# Windows, PowerShell
$env:API_TOKEN = "ihr-token"
# Linux und macOS
export API_TOKEN="ihr-token"
Das genaue Header-Format (Bearer, Token, ein Schlüssel in einem eigenen Header) hängt von der API ab: Sie finden es immer in deren Dokumentation.
Fehler behandeln
In einem echten Skript kann das Netz nicht antworten, der Server in Wartung sein oder der Token ablaufen. Mit einem try-Block können Sie jeden Fall mit einer klaren Meldung behandeln:
import requests
try:
response = requests.get(URL, params=params, timeout=10)
response.raise_for_status()
except requests.exceptions.Timeout:
print("Der Server hat nicht rechtzeitig geantwortet.")
except requests.exceptions.HTTPError as error:
print(f"HTTP-Fehler {error.response.status_code}: {error.response.text[:200]}")
except requests.exceptions.ConnectionError:
print("Verbindung fehlgeschlagen: Netzwerk oder Adresse prüfen.")
else:
data = response.json()
print(data)
Der else-Block wird nur ausgeführt, wenn keine Fehler aufgetreten sind. Einen Teil des Antworttexts auszugeben (error.response.text) ist hilfreich, weil viele APIs dort den Grund für den Fehler erklären.
Sessions und automatische Wiederholungen
Stellt das Skript viele Anfragen an denselben Dienst, lohnt sich eine Session: Sie verwendet die Verbindung wieder (und ist daher schneller) und erlaubt es, gemeinsame Header und Verhaltensweisen nur einmal festzulegen. Mit einer Session können Sie außerdem Anfragen, die an vorübergehenden Problemen gescheitert sind, automatisch wiederholen lassen:
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
retries = Retry(
total=3, # bis zu 3 neue Versuche
backoff_factor=1, # steigende Wartezeiten zwischen den Versuchen
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET"], # nur Lesezugriffe wiederholen
)
session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retries))
session.headers.update({"User-Agent": "mein-skript/1.0"})
response = session.get(URL, params=params, timeout=10)
response.raise_for_status()
Warum nur GET-Anfragen wiederholen? Weil doppeltes Lesen keinen Schaden anrichtet, ein wiederholtes POST aber dasselbe Element zweimal erstellen könnte, zum Beispiel zwei identische Bestellungen.
Bewährte Vorgehensweisen
- Setzen Sie immer einen Timeout, bei jeder Anfrage.
- Prüfen Sie den Statuscode mit
raise_for_status(), bevor Sie die Daten verwenden. - Schreiben Sie Tokens und Passwörter nie in den Code: Verwenden Sie Umgebungsvariablen.
- Halten Sie die Limits der API ein: Viele APIs begrenzen die Zahl der Anfragen. Erhalten Sie einen Fehler
429, werden Sie langsamer; manche geben im HeaderRetry-Afteran, wie viele Sekunden Sie warten sollen. - Berücksichtigen Sie die Paginierung: APIs, die lange Listen liefern, teilen sie in Seiten auf. Die Dokumentation sagt Ihnen, welchen Parameter Sie verwenden (zum Beispiel
pageodercursor), um die nächsten Seiten abzurufen. - Lesen Sie die Dokumentation der API: Adressen, Parameter und Authentifizierungsformat unterscheiden sich von Dienst zu Dienst.
Und httpx?
Ihnen könnte auch httpx begegnen, eine neuere Bibliothek mit einer sehr ähnlichen Schnittstelle wie requests, die zusätzlich asynchrone Anfragen unterstützt (also viele Anfragen parallel). Für Skripte und Automatisierungen bleibt requests die einfachste Wahl; sollten Sie eines Tages asynchrone Funktionen brauchen, fällt der Umstieg auf httpx leicht.
Offizielle Quellen
Teilen
Was ist Ihre Reaktion?
Gefällt mir
0
Gefällt mir nicht
0
Liebe
0
Lustig
0
Wütend
0
Traurig
0
Wow
0