Appeler une API REST avec Python et requests : exemples pratiques

Comment utiliser la bibliothèque requests pour lire et envoyer des données à une API REST en Python : requêtes GET et POST, JSON, authentification, erreurs et nouvelles tentatives.

Appeler une API REST avec Python et requests : exemples pratiques

Une grande partie des services que nous utilisons chaque jour, des prévisions météo aux logiciels de gestion d’entreprise, met ses données à disposition via une API. Savoir l’utiliser depuis Python permet d’automatiser une foule de tâches : télécharger des données, synchroniser deux services, publier des contenus, générer des rapports.

Dans ce guide, nous utilisons requests, la bibliothèque la plus répandue pour cet usage, avec des exemples que vous pouvez exécuter tout de suite sur des API publiques et gratuites.

Qu’est-ce qu’une API REST, en bref

Une API (Application Programming Interface) est un moyen pour un programme de demander des données ou des actions à un autre programme. Les API REST fonctionnent via le web, avec le même protocole que les sites, HTTP. Il n’y a que quelques notions à connaître :

  • Endpoint : l’adresse à laquelle on envoie la requête, par exemple https://api.example.com/clients.
  • Méthode : le type d’opération. Les principales sont GET (lire), POST (créer), PUT ou PATCH (modifier) et DELETE (supprimer).
  • JSON : le format texte généralement utilisé pour échanger les données. En Python, il devient un dictionnaire ou une liste.
  • Code de statut : un nombre qui indique le résultat. 200 et 201 signifient succès ; 4xx indique une erreur dans la requête (par exemple 401 non autorisé, 404 introuvable, 429 trop de requêtes) ; 5xx indique un problème du serveur.

Installer requests

Comme toujours, mieux vaut travailler dans un environnement virtuel. Avec l’environnement actif :

python -m pip install requests

La première requête GET : la météo

Nous utilisons Open-Meteo, un service météo gratuit qui ne demande pas d’inscription. Demandons la météo actuelle à Milan :

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"Température : {current['temperature_2m']} °C")
print(f"Vent : {current['wind_speed_10m']} km/h")

Voyons les lignes importantes :

  • params : requests ajoute les paramètres à l’adresse dans le bon format, en gérant aussi les espaces et les caractères spéciaux. Inutile de composer l’URL à la main.
  • timeout=10 : si le serveur ne répond pas dans les 10 secondes, la requête s’interrompt. Sans timeout, un script peut rester bloqué indéfiniment. Mettez-en toujours un.
  • raise_for_status() : si le code de statut indique une erreur, il lève une exception au lieu de continuer avec des données erronées.
  • json() : transforme la réponse en dictionnaire Python.

Un conseil pratique : quand vous travaillez avec une nouvelle API, affichez la réponse complète avec print(data) pour voir sa structure, avant d’extraire les champs qui vous intéressent.

Envoyer des données avec une requête POST

Pour créer quelque chose, on utilise la méthode POST. Pour essayer sans risque, nous utilisons JSONPlaceholder, un service de test qui simule une vraie API mais n’enregistre rien :

import requests

new_post = {
    "title": "Essai",
    "body": "Contenu d’essai",
    "userId": 1,
}

response = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=new_post,
    timeout=10,
)
response.raise_for_status()

print(response.status_code)   # 201 : créé
print(response.json())        # les données reçues, avec l’id attribué

Le paramètre json= convertit le dictionnaire en JSON et définit automatiquement l’en-tête Content-Type: application/json. C’est différent de data=, qui envoie les données comme un formulaire web : si une API attend du JSON, utilisez toujours json=.

Authentification par jeton

Les API privées exigent de s’identifier. La méthode la plus courante est un jeton (ou clé d’API) envoyé dans les en-têtes de la requête :

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/clients",
    headers=headers,
    timeout=10,
)

Notez que le jeton n’est pas écrit dans le code : il est lu depuis une variable d’environnement. C’est une règle de sécurité importante : si le code se retrouve sur GitHub ou est partagé, le jeton reste privé. Pour définir la variable avant de lancer le script :

# Windows, invite de commandes
set API_TOKEN=votre-jeton

# Windows, PowerShell
$env:API_TOKEN = "votre-jeton"

# Linux et macOS
export API_TOKEN="votre-jeton"

Le format exact de l’en-tête (Bearer, Token, une clé dans un en-tête dédié) dépend de l’API : vous le trouverez toujours dans sa documentation.

Gérer les erreurs

Dans un vrai script, le réseau peut ne pas répondre, le serveur peut être en maintenance, le jeton peut expirer. Avec un bloc try, vous pouvez gérer chaque cas avec un message clair :

import requests

try:
    response = requests.get(URL, params=params, timeout=10)
    response.raise_for_status()
except requests.exceptions.Timeout:
    print("Le serveur n’a pas répondu à temps.")
except requests.exceptions.HTTPError as error:
    print(f"Erreur HTTP {error.response.status_code} : {error.response.text[:200]}")
except requests.exceptions.ConnectionError:
    print("Connexion impossible : vérifiez le réseau ou l’adresse.")
else:
    data = response.json()
    print(data)

Le bloc else n’est exécuté que s’il n’y a pas eu d’erreur. Afficher une partie du texte de la réponse (error.response.text) est utile, car beaucoup d’API y expliquent la raison de l’erreur.

Sessions et nouvelles tentatives automatiques

Si le script fait beaucoup de requêtes vers le même service, mieux vaut utiliser une session : elle réutilise la connexion (elle est donc plus rapide) et permet de définir une seule fois les en-têtes et comportements communs. Avec une session, vous pouvez aussi relancer automatiquement les requêtes qui ont échoué à cause de problèmes temporaires :

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retries = Retry(
    total=3,                     # jusqu’à 3 nouvelles tentatives
    backoff_factor=1,            # attentes croissantes entre les tentatives
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET"],     # ne relancer que les lectures
)

session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retries))
session.headers.update({"User-Agent": "mon-script/1.0"})

response = session.get(URL, params=params, timeout=10)
response.raise_for_status()

Pourquoi ne relancer que les requêtes GET ? Parce que lire deux fois ne fait pas de dégâts, alors que répéter un POST pourrait créer deux fois le même élément, par exemple deux commandes identiques.

Bonnes pratiques

  • Définissez toujours un timeout, pour chaque requête.
  • Vérifiez le code de statut avec raise_for_status() avant d’utiliser les données.
  • N’écrivez jamais de jetons ni de mots de passe dans le code : utilisez des variables d’environnement.
  • Respectez les limites de l’API : beaucoup d’API limitent le nombre de requêtes. Si vous recevez une erreur 429, ralentissez ; certaines indiquent dans l’en-tête Retry-After combien de secondes attendre.
  • Gérez la pagination : les API qui renvoient de longues listes les découpent en pages. La documentation indique quel paramètre utiliser (par exemple page ou cursor) pour demander les pages suivantes.
  • Lisez la documentation de l’API : adresses, paramètres et format d’authentification changent d’un service à l’autre.

Et httpx ?

Vous croiserez peut-être aussi httpx, une bibliothèque plus récente avec une interface très proche de requests, qui prend aussi en charge les requêtes asynchrones (c’est-à-dire de nombreuses requêtes en parallèle). Pour les scripts et l’automatisation, requests reste le choix le plus simple ; si un jour vous avez besoin des fonctions asynchrones, le passage à httpx sera naturel.

Sources officielles

Partager

Quelle est votre réaction ?

Aimer Aimer 0
Je n'aime pas Je n'aime pas 0
Amour Amour 0
Drôle Drôle 0
En colère En colère 0
Triste Triste 0
Waouh Waouh 0