Travailler avec l'API en Python : un guide complet de la bibliothèque requests

Pourquoi requests ?

Python inclut un module urllib intégré pour travailler avec HTTP, mais sa syntaxe est lourde et peu intuitive. La bibliothèque requests résout ce problème en fournissant une interface élégante et intuitive. Ce n'est pas pour rien que son slogan est « HTTP for Humans ».

Installation

Définir des requêtes est un jeu d'enfant :

pip install requests

Bases de travail : requêtes GET

Commençons par le type de requête le plus courant : GET. Imaginons que nous devons obtenir des données sur un utilisateur de GitHub :

import requests

response = requests.get('https://api.github.com/users/octocat')

# Vérification du statut de la réponse
print(response.status_code)  # 200

# Nous obtenons JSON
data = response.json()
print(data['name'])  # The Octocat
print(data['public_repos'])  # Nombre de dépôts publics

L'objet response contient toutes les informations sur la réponse du serveur : code d'état, en-têtes, corps de la réponse et bien plus encore.

Paramètres de la requête

Les API nécessitent souvent la transmission de paramètres dans l'URL. La bibliothèque requests vous permet de le faire avec élégance :

# Recherche de dépôts sur GitHub
params = {
    'q': 'python requests',
    'sort': 'stars',
    'order': 'desc'
}

response = requests.get('https://api.github.com/search/repositories', params=params)
repos = response.json()

for repo in repos['items'][:5]:
    print(f"{repo['name']}: {repo['stargazers_count']} stars")

La bibliothèque génère automatiquement l'URL correcte avec les paramètres, en échappant les caractères spéciaux.

Requêtes POST et envoi de données

Les requêtes POST sont utilisées pour créer des ressources ou envoyer des formulaires. Prenons un exemple avec l'envoi de JSON :

# Création d'une nouvelle ressource
data = {
    'title': 'I'm studying requests',
    'body': 'This is a very convenient library!',
    'userId': 1
}

response = requests.post('https://jsonplaceholder.typicode.com/posts', json=data)

if response.status_code == 201:
    print('Resource created!')
    print(response.json())

Faites attention au paramètre json — requests sérialise automatiquement le dictionnaire en JSON et définit l'en-tête correct Content-Type.

Utilisation des titres

De nombreuses API nécessitent une authentification via des en-têtes. Voici comment cela se fait :

headers = {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'User-Agent': 'MyApp/1.0'
}

response = requests.get('https://api.example.com/data', headers=headers)

Certaines API utilisent des clés API :

headers = {'X-API-Key': 'your_api_key'}
response = requests.get('https://api.example.com/protected', headers=headers)

Traitement des erreurs

Le travail professionnel avec l'API est impossible sans un traitement correct des erreurs :

try:
    response = requests.get('https://api.example.com/data', timeout=5)
    response.raise_for_status()  # Lance une exception pour les codes 4xx et 5xx
    
    data = response.json()
    
except requests.exceptions.HTTPError as http_err:
    print(f'HTTP error: {http_err}')
except requests.exceptions.ConnectionError:
    print('Connection error')
except requests.exceptions.Timeout:
    print('Timeout')
except requests.exceptions.RequestException as err:
    print(f'An error occurred: {err}')

La méthode raise_for_status() lève automatiquement une exception si le serveur a renvoyé un code d'erreur.

Sessions pour requêtes multiples

Si vous devez effectuer plusieurs requêtes à une seule API, utilisez des sessions. Ils enregistrent les cookies et la connexion, ce qui accélère considérablement le travail :

session = requests.Session()
session.headers.update({'Authorization': 'Bearer TOKEN'})

# Toutes les requêtes au sein de la session utiliseront des en-têtes communs
response1 = session.get('https://api.example.com/users')
response2 = session.get('https://api.example.com/posts')
response3 = session.post('https://api.example.com/comments', json={'text': 'Hello'})

session.close()

Il est encore préférable d'utiliser le gestionnaire contextuel :

with requests.Session() as session:
    session.headers.update({'Authorization': 'Bearer TOKEN'})
    response = session.get('https://api.example.com/data')

Gestion des fichiers

Le téléchargement de fichiers via l'API n'est pas difficile non plus :

# Chargement du fichier
files = {'file': open('document.pdf', 'rb')}
response = requests.post('https://api.example.com/upload', files=files)

# Téléchargement du fichier
response = requests.get('https://example.com/image.jpg', stream=True)
with open('image.jpg', 'wb') as file:
    for chunk in response.iter_content(chunk_size=8192):
        file.write(chunk)

Le paramètre stream=True vous permet de télécharger de gros fichiers par portions sans les télécharger complètement en mémoire.

Exemple pratique : travailler avec l'API météo

Créons une application météo complète :

import requests

def get_weather(city, api_key):
    """Gets the current weather for the specified city"""
    base_url = "http://api.openweathermap.org/data/2.5/weather"
    
    params = {
        'q': city,
        'appid': api_key,
        'units': 'metric',
        'lang': 'ru'
    }
    
    try:
        response = requests.get(base_url, params=params, timeout=10)
        response.raise_for_status()
        
        data = response.json()
        
        weather_info = {
            'city': data['name'],
            'temperature': data['main']['temp'],
            'feels': data['main']['feels_like'],
            'description': data['weather'][0]['description'],
            'Humidity': data['main']['humidity'],
            'Wind': data['wind']['speed']
        }
        
        return weather_info
        
    except requests.exceptions.RequestException as e:
        print(f"Error retrieving data: {e}")
        return None

# Utilisation
weather = get_weather('Moscow', 'YOUR_API_KEY')
if weather:
    print(f"Weather in the city {weather['city']}:"
    print(f"Temperature: {weather['temperature']}°C")
    print(f"Feels like: {weather['ощущается']}°C"  print(f"Description: {weather['description']}"]}")

Options avancées

Mécanisme de réessai à l'aide d'adaptateurs :

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

session = requests.Session()
retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry)
session.mount('http://', adapter)
session.mount('https://', adapter)

response = session.get('https://api.example.com/data')

Travail avec authentification :

# Basic Auth
response = requests.get('https://api.example.com/data', 
                       auth=('username', 'password'))

# OAuth 2.0 généralement via les en-têtes
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get('https://api.example.com/data', headers=headers)

Conclusion

La bibliothèque requests transforme le travail avec l'API en Python en plaisir. Une syntaxe simple et intuitive, des fonctionnalités puissantes et une excellente documentation en font la norme de facto pour les requêtes HTTP en Python. Après avoir maîtrisé les requêtes, vous pourrez intégrer des milliers de services différents dans vos projets et créer des applications vraiment puissantes.

Annexe Code propose des cours structurés sur Python, JavaScript, les API et bien plus encore. Des tutoriels interactifs, des exercices pratiques et un apprentissage étape par étape vous aideront à devenir développeur.

Rejoignez notre Chaîne Telegram, où vous trouverez le soutien de développeurs expérimentés, des ressources utiles et des réponses à toutes vos questions de programmation. Apprenez à votre rythme avec une communauté de personnes partageant les mêmes idées !