Consommer une API REST en Python se résume à envoyer des requêtes HTTP vers des URLs structurées et à traiter les réponses, le plus souvent au format JSON. La bibliothèque requests est le point d’entrée standard pour cette tâche : elle encapsule toute la complexité du protocole HTTP en quelques fonctions lisibles. Avant de plonger dans la documentation d’une API tierce, il vaut mieux maîtriser ce socle technique, qui reste le même quelle que soit l’API consommée.
Ce que fait réellement une API REST quand Python l’appelle
Une API REST expose des ressources accessibles via des URLs, appelées endpoints. Chaque endpoint répond à des méthodes HTTP précises : GET pour lire une ressource, POST pour en créer une, PUT ou PATCH pour la modifier, DELETE pour la supprimer. Le serveur répond avec un code de statut HTTP et, dans la grande majorité des cas, un corps JSON.
Ce modèle est important à comprendre avant de lire une documentation. La plupart des docs d’API sont organisées par endpoint et par méthode : si vous savez déjà ce que signifient ces termes, vous gagnez un temps considérable. Vous cherchez à lire des données ? Rendez-vous directement à la section GET. Vous voulez créer une entrée ? Section POST.
Les codes de statut suivent une logique stable : 2xx indique un succès, 4xx une erreur côté client (mauvais paramètre, authentification manquante, accès refusé), 5xx une erreur côté serveur. Un code 403 ne signifie pas toujours « accès refusé » au sens strict : certaines API, notamment GitHub, le renvoient aussi en cas de dépassement de limite de débit, avec un en-tête Retry-After indiquant quand relancer l’appel.
Installer requests et envoyer une première requête GET
La bibliothèque requests ne fait pas partie de la bibliothèque standard Python. Elle s’installe via pip :
pip install requests
Une première requête GET s’écrit en trois lignes :
import requestsresponse = requests.get("https://jsonplaceholder.typicode.com/posts/1")print(response.json())
jsonplaceholder.typicode.com est une API publique de test, sans clé d’authentification, qui renvoie des données JSON fictives. C’est l’environnement idéal pour comprendre la mécanique avant d’attaquer une API de production.
L’objet response contient tout ce dont vous avez besoin : le code de statut (response.status_code), le corps brut (response.text) et le corps désérialisé en dictionnaire Python (response.json()).
Paramètres, en-têtes et authentification dans une requête Python
La plupart des APIs nécessitent des paramètres de filtrage ou une clé d’authentification. requests les gère via des arguments dédiés, sans avoir à construire l’URL manuellement.
- Paramètres de requête (query string) : passés sous forme de dictionnaire à l’argument
params. Requests encode automatiquement les valeurs dans l’URL. Exemple :requests.get(url, params={"userId": 1})génèreurl?userId=1. - En-têtes HTTP : l’argument
headersaccepte un dictionnaire. C’est ici que l’on place un token d’authentification Bearer :headers={"Authorization": "Bearer MON_TOKEN"}. Ne jamais écrire un token directement dans le code source ; le lire depuis une variable d’environnement ou un fichier.env. - Corps JSON pour les requêtes POST : l’argument
jsonsérialise automatiquement un dictionnaire Python en JSON et positionne l’en-têteContent-Type: application/json. Utiliserjson=dataplutôt quedata=json.dumps(data)évite une source d’erreur fréquente.
Pour POST, la structure ressemble à ceci :
response = requests.post(url, json={"title": "test", "body": "contenu"}, headers={"Authorization": "Bearer MON_TOKEN"})
Timeout et gestion des erreurs : ce que la documentation ne met pas en avant
Un appel requests sans timeout peut attendre indéfiniment si le serveur ne répond pas. En production, tout appel HTTP doit inclure un paramètre timeout.
Ce paramètre accepte soit une valeur unique (délai global), soit un tuple qui distingue le délai de connexion du délai de lecture : timeout=(3, 10) signifie « attendre au maximum 3 secondes pour établir la connexion, et 10 secondes entre deux octets reçus ». Le délai de lecture ne limite pas la durée totale du téléchargement, il limite l’attente entre deux paquets.
Pour détecter les erreurs HTTP sans vérifier manuellement le code de statut, la méthode raise_for_status() lève une exception si le code est 4xx ou 5xx :
response = requests.get(url, timeout=(3, 10))response.raise_for_status()
Une nuance importante sur les relances automatiques : relancer un POST après une erreur réseau peut créer un doublon. Une erreur de lecture peut survenir après que le serveur a déjà traité la requête. Les relances automatiques sont adaptées aux requêtes GET (idempotentes par nature) ; pour POST, une vérification préalable est préférable.
Lire une documentation d’API sans s’y perdre
La documentation d’une API peut sembler dense, mais elle suit toujours la même logique. Une fois la méthode HTTP et l’endpoint identifiés, l’essentiel se trouve dans trois sections.
La section Authentication explique comment passer vos identifiants. La section Parameters (ou Query Parameters / Request Body) liste ce que vous pouvez envoyer. La section Response décrit la structure JSON retournée, avec les champs disponibles.
Une approche efficace consiste à tester d’abord l’endpoint avec un outil comme curl ou Postman avant d’écrire du Python. Cela isole les problèmes : si l’appel échoue dans Postman, le problème vient de votre requête ou de vos identifiants, pas de votre code Python. Si Postman réussit mais Python échoue, vous savez où chercher.
Quand une réponse JSON est complexe, utiliser print(response.json().keys()) ou import json; print(json.dumps(response.json(), indent=2)) permet de visualiser la structure avant d’y naviguer.
httpx comme alternative à requests pour les contextes asynchrones
La bibliothèque requests est synchrone : elle bloque le programme pendant l’attente d’une réponse. Dans un contexte où plusieurs appels HTTP doivent être effectués en parallèle, ou dans une application basée sur asyncio, httpx offre une API très proche de requests mais compatible avec async/await.
Le choix entre les deux dépend du modèle d’exécution de votre projet. Pour un script simple ou un pipeline de données séquentiel, requests reste la solution la plus directe. Pour une application FastAPI ou un scraper concurrent, httpx évite de bloquer la boucle d’événements.
Maîtriser requests en premier reste pertinent dans tous les cas : la logique des paramètres, des en-têtes et de la gestion des erreurs est identique dans httpx, et passer de l’un à l’autre ne demande que quelques ajustements syntaxiques.
