IUT
Intermédiaire

La bibliothèque requests

requests est le standard de facto pour les requêtes HTTP en Python. C'est elle qui va remplacer vos imports directs par des appels réseau.

Installation

requests n'est pas incluse dans la bibliothèque standard Python. Installez-la avec pip :

bash
pip install requests

Vérification

Pour vérifier que l'installation a fonctionné :

python
import requests
print(requests.__version__)

Première requête GET

Un appel à votre API Flask avec requests :

python
import requests

response = requests.get("http://localhost:5000/api/v1/ventes/par-region")
print(response.status_code)  # 200
print(response.json())       # {"data": [...]}

requests.get() envoie une requête HTTP GET à l'URL spécifiée et retourne un objet Response.

L'objet Response

L'objet retourné par requests.get() contient toutes les informations de la réponse HTTP :

PropriétéTypeDescription
response.status_codeintCode HTTP de la réponse (200, 404, 500...)
response.okboolTrue si le code est inférieur à 400
response.json()dict ou listParse le body JSON en objet Python
response.textstrLe body brut en texte
response.headersdictLes headers de la réponse HTTP

En pratique :

python
response = requests.get("http://localhost:5000/api/v1/ventes/par-region")

print(response.status_code)   # 200
print(response.ok)            # True
print(response.headers["Content-Type"])  # application/json

data = response.json()        # {"data": [...], "total": 12}
print(type(data))             # <class 'dict'>
print(len(data["data"]))      # 12

Que retourne response.ok si le serveur renvoie un code 404 ?

Le paramètre params

Pour envoyer des paramètres de requête (query string), utilisez le paramètre params :

python
response = requests.get(
    "http://localhost:5000/api/v1/ventes/par-region",
    params={"region": "IDF", "annee": 2024, "page": 1, "per_page": 50}
)
# URL générée : .../par-region?region=IDF&annee=2024&page=1&per_page=50

Ne construisez jamais l'URL manuellement

Évitez les f-strings pour ajouter des paramètres :

python
# ❌ Mauvaise pratique
url = f"http://localhost:5000/api/v1/ventes/par-region?region={region}&annee={annee}"

# ✅ Bonne pratique
response = requests.get(url, params={"region": region, "annee": annee})

Le paramètre params gère automatiquement l'encodage des caractères spéciaux (espaces, accents, &, etc.). Une f-string peut produire une URL invalide.

Les valeurs None dans le dictionnaire params sont automatiquement ignorées — pratique pour les filtres optionnels :

python
# Si annee vaut None, le paramètre n'est pas envoyé
params = {"region": region, "annee": annee}  # annee=None → pas inclus dans l'URL
response = requests.get(url, params=params)

De JSON à DataFrame

Votre API retourne du JSON, mais Streamlit et Plotly travaillent avec des DataFrames pandas. La conversion :

python
import pandas as pd
import requests

response = requests.get(
    "http://localhost:5000/api/v1/ventes/par-region",
    params={"annee": 2024}
)

data = response.json()           # {"data": [...], "total": 12}
df = pd.DataFrame(data["data"])  # Conversion en DataFrame

Structure de la réponse API

Rappelez-vous la structure de vos réponses API (séance 1) : les données sont dans la clé "data" du JSON retourné. C'est pourquoi on écrit data["data"] et non pas data directement.

Dans Streamlit :

python
import streamlit as st
import pandas as pd
import requests
import plotly.express as px

# Appel API
response = requests.get(
    "http://localhost:5000/api/v1/ventes/par-region",
    params={"annee": 2024}
)

data = response.json()
df = pd.DataFrame(data["data"])

# Affichage dans Streamlit
fig = px.bar(df, x="region", y="chiffre_affaires", title="CA par région")
st.plotly_chart(fig, use_container_width=True)

Pourquoi utiliser params={...} plutôt qu'une f-string pour les paramètres d'URL ?

À retenir

Points clés

  • requests.get(url) envoie une requête HTTP GET et retourne un objet Response
  • Les propriétés clés : status_code, ok, json(), text, headers
  • Utilisez le paramètre params pour les query strings — jamais de f-strings
  • response.json() convertit le JSON en dict/list Python
  • pd.DataFrame(data["data"]) convertit les données API en DataFrame pour Plotly

Ressources

Documentation officielle requests

Guide complet de la bibliothèque requests

Documentation

requests — Quickstart

Tutoriel de démarrage rapide pour requests

Documentation

Le code fonctionne, mais que se passe-t-il si l'API est éteinte, si elle met trop de temps à répondre, ou si elle retourne une erreur ?