Skip to content

FastAPI Aide-mémoire

Framework web Python moderne et rapide pour construire des API.

01

Démarrage

Première API

FastAPI repose sur Starlette et Pydantic. uvicorn est le serveur ASGI. --reload active le rechargement automatique pendant le développement.

fastapi
# install FastAPI and uvicorn
pip install fastapi uvicorn

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

# run: uvicorn main:app --reload

Lancer avec Uvicorn

L'instance d'app 'main:app' signifie module 'main', variable 'app'. Utilisez --reload uniquement en développement ; en production, lancez sans lui et utilisez un gestionnaire de processus.

fastapi
# development with auto-reload
uvicorn main:app --reload

# specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000

# run programmatically
import uvicorn
if __name__ == "__main__":
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

Opérations de chemin asynchrones

Vous pouvez déclarer les opérations de chemin avec 'def' (exécutées dans un threadpool) ou 'async def'. Utilisez async def quand la fonction fait des E/S via des bibliothèques asynchrones ; mélanger des appels bloquants dans async def bloquera la boucle d'événements.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "hello"}

@app.get("/sync")
def read_sync():
    return {"message": "sync also works"}

# use async when calling async libs (httpx, databases)
@app.get("/data")
async def fetch_data():
    import httpx
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.example.com")
    return r.json()

Décorateurs d'opérations de chemin

FastAPI gère toutes les méthodes HTTP : GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD. Chacune correspond à un décorateur. Utilisez status_code= sur le décorateur pour remplacer le statut de succès par défaut.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def list_items(): ...

@app.post("/items")
def create_item(): ...

@app.put("/items/{item_id}")
def replace_item(item_id: int): ...

@app.patch("/items/{item_id}")
def update_item(item_id: int): ...

@app.delete("/items/{item_id}")
def delete_item(item_id: int): ...

@app.options("/items")
def options_items(): ...

@app.head("/items")
def head_items(): ...

Réponse JSON et statut

Renvoyer un dict/list est automatiquement converti en JSON avec 200 (ou votre status_code). Pour un contrôle total du statut, des en-têtes ou du contenu, renvoyez directement une JSONResponse ou une Response.

fastapi
from fastapi import FastAPI, status
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/plain")
def plain():
    return {"key": "value"}  # auto JSON, 200 OK

@app.post("/created", status_code=status.HTTP_201_CREATED)
def created():
    return {"id": 1}

@app.get("/custom")
def custom():
    return JSONResponse(
        status_code=418,
        content={"error": "I'm a teapot"},
        headers={"X-Custom": "yes"},
    )

Structure de projet

Découpez une app qui grandit en modules avec APIRouter, puis enregistrez-les via app.include_router(). Gardez les schémas Pydantic, la config DB et les dépendances dans des fichiers séparés pour la maintenabilité.

fastapi
myapp/
  main.py              # creates the FastAPI app
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
  models/
    schemas.py         # Pydantic models
    database.py        # DB engine & session
  dependencies.py      # shared Depends functions
  tests/
    test_main.py

# main.py
from fastapi import FastAPI
from routers import users, items
app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/items")
02

Paramètres de chemin

Paramètres de chemin de base

Les valeurs capturées dans le chemin sont des chaînes, sauf annotation de type. Le nom du paramètre dans le chemin doit correspondre exactement au nom de l'argument de la fonction.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id):
    return {"item_id": item_id}

# GET /items/42 -> {"item_id": "42"}  (string by default)

Conversion de type

Ajouter une annotation de type (int, float, bool, str, Enum) fait valider et convertir la valeur du chemin par FastAPI. Les valeurs invalides renvoient une réponse 422 avec un message d'erreur clair.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

# GET /items/3   -> {"item_id": 3}
# GET /items/abc -> 422 Validation Error (not an integer)

Validation du chemin

Path() ajoute métadonnées et contraintes à un paramètre de chemin. Contraintes numériques : ge (>=), gt (>), le (<=), lt (<). Les paramètres de chemin sont toujours requis, Path() ne peut donc pas définir de défaut.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(
    item_id: int = Path(
        title="The ID of the item",
        description="Must be a positive integer",
        ge=1,
        le=1000,
    ),
):
    return {"item_id": item_id}

Contraintes numériques

Utilisez ge/gt/le/lt sur des paramètres de chemin int ou float pour imposer des plages numériques. Des contraintes combinées donnent une validation de bornes précise avec erreurs 422 automatiques.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/ratio/{value}")
def ratio(
    value: float = Path(gt=0, lt=1),  # 0 < value < 1
):
    return {"value": value}

@app.get("/page/{page}")
def page(
    page: int = Path(ge=1),       # >= 1
    size: int = Path(le=100),     # <= 100
):
    return {"page": page, "size": size}

L'ordre des routes compte

Les routes sont appariées dans l'ordre de déclaration. Déclarez les chemins spécifiques comme /users/me avant les motifs dynamiques comme /users/{user_id}, sinon la route dynamique masquera la spécifique.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/users/me")
def read_current_user():
    return {"user": "me"}

@app.get("/users/{user_id}")
def read_user(user_id: str):
    return {"user_id": user_id}

# /users/me MUST be declared before /users/{user_id}
# otherwise 'me' would match the {user_id} pattern

Paramètres de chemin Enum

Utiliser un type Enum pour un paramètre de chemin le restreint aux valeurs prédéfinies et génère un schéma enum dans la doc OpenAPI. Héritez de (str, Enum) pour que les valeurs se sérialisent en chaînes.

fastapi
from enum import Enum
from fastapi import FastAPI

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

app = FastAPI()

@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model": model_name, "layers": 5}
    return {"model": model_name}

# GET /models/resnet -> {"model": "resnet"}
03

Paramètres de requête

Paramètres de requête de base

Les paramètres de fonction qui ne sont PAS dans le chemin deviennent des paramètres de requête. Fournir une valeur par défaut les rend optionnels ; le défaut s'applique quand la clé de requête est absente.

fastapi
from fastapi import FastAPI

app = FastAPI()

fake_items = [{"item": "a"}, {"item": "b"}, {"item": "c"}]

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
    return fake_items[skip : skip + limit]

# GET /items?skip=0&limit=2
# GET /items                -> skip=0, limit=10

Paramètres de requête optionnels

Utilisez Optional[str] = None (ou str | None = None sur Python 3.10+) pour un paramètre de requête qui peut être omis. Les paramètres requis n'ont simplement pas de valeur par défaut.

fastapi
from typing import Optional
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: str, q: Optional[str] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

# GET /items/1?q=hello
# GET /items/1            (q is None)

Validation de requête

Query() ajoute de la validation : min_length/max_length pour les chaînes, ge/gt/le/lt pour les nombres, pattern (regex) pour le format des chaînes. Utilisez default= pour fixer une valeur tout en appliquant les contraintes.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/search")
def search(q: str = Query(min_length=3, max_length=50, pattern="^[a-zA-Z]+$")):
    return {"q": q}

@app.get("/page")
def page(limit: int = Query(default=10, ge=1, le=100)):
    return {"limit": limit}

Conversion booléenne

Les paramètres booléens de requête acceptent plusieurs valeurs truthy : true, 1, yes, on (insensible à la casse). Tout le reste est interprété comme false. Les types invalides comme ?active=maybe renvoient 422.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/flags")
def flags(active: bool = False):
    return {"active": active}

# GET /flags?active=true   -> {"active": true}
# GET /flags?active=1      -> {"active": true}
# GET /flags?active=yes    -> {"active": true}
# GET /flags?active=off    -> {"active": false}

Paramètres de requête en liste

Un paramètre List[str] accepte la même clé répétée dans la query string. Utilisez Query(default=[]) pour une liste vide par défaut, ou Query(default=None) pour autoriser l'absence de valeur.

fastapi
from typing import List
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def list_items(q: List[str] = Query(default=[])):
    return {"q": q}

# GET /items?q=a&q=b&q=c  -> {"q": ["a", "b", "c"]}
# declare default=None to accept a list or null

Paramètres de requête requis

Utilisez Query(...) (l'Ellipsis) pour déclarer un paramètre de requête requis qui garde ses métadonnées de validation. Sans défaut et sans Query(...), un paramètre simplement annoté est aussi requis.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def read_item(q: str = Query(...)):
    return {"q": q}

# GET /items?q=hello   -> ok
# GET /items           -> 422 (q is required)
# Query(...) (Ellipsis) marks a parameter as required
04

Corps de requête (Pydantic)

Bases de BaseModel

Un BaseModel Pydantic déclaré comme paramètre de fonction devient le corps JSON de la requête. FastAPI valide la charge utile, convertit les types et renvoie 422 sur des données invalides. Les champs avec défauts sont optionnels.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    in_stock: bool = True

app = FastAPI()

@app.post("/items")
def create_item(item: Item):
    return item

# POST /items  body: {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5, "in_stock": true}

Types et contraintes de champs

Field() ajoute contraintes et métadonnées aux attributs du modèle : min_length/max_length pour les chaînes, gt/ge/lt/le pour les nombres, default_factory pour les défauts mutables. model_config avec json_schema_extra ajoute des exemples à la doc.

fastapi
from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0, description="must be positive")
    tax: Optional[float] = None
    tags: list[str] = Field(default_factory=list)

    model_config = {
        "json_schema_extra": {
            "examples": [{"name": "Apple", "price": 0.5, "tags": ["fruit"]}]
        }
    }

Modèles imbriqués

Les modèles peuvent s'imbriquer : déclarez un autre BaseModel comme type de champ. FastAPI valide toute la structure imbriquée récursivement, et le schéma OpenAPI généré reflète les objets imbriqués.

fastapi
from pydantic import BaseModel
from typing import Optional

class Image(BaseModel):
    url: str
    name: str

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    image: Optional[Image] = None
    images: list[Image] = []

# valid body:
# {"name": "Phone", "image": {"url": "http://x/a.png", "name": "a"}}

Validation de champ

Utilisez @field_validator (Pydantic v2) pour ajouter une logique de validation personnalisée par champ. Levez ValueError pour rejeter l'entrée (FastAPI la présente en 422). Renvoyez la valeur (éventuellement transformée) pour la conserver.

fastapi
from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str
    email: str

    @field_validator("email")
    @classmethod
    def email_must_contain_at(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("must contain @")
        return v.lower()

    @field_validator("name")
    @classmethod
    def name_stripped(cls, v: str) -> str:
        return v.strip()

Champs optionnels et par défaut

Un champ n'est requis que s'il n'a pas de défaut et n'est pas Optional. Optional[str] = None est le pattern standard pour un champ nullable optionnel ; un défaut simple comme 0.0 rend un champ optionnel avec cette valeur.

fastapi
from pydantic import BaseModel
from typing import Optional

class Item(BaseModel):
    name: str                       # required
    description: Optional[str] = None  # optional, defaults to None
    price: float = 0.0              # optional, defaults to 0.0
    tags: list[str] = []            # optional, defaults to empty list

# All of these are valid:
# {"name": "X"}
# {"name": "X", "price": 9.99, "tags": ["a"]}

Corps avec chemin et requête

Paramètres de chemin, de requête et de corps peuvent coexister dans une même opération. FastAPI décide ainsi : paramètre de chemin s'il est dans le chemin, modèle Pydantic (ou Body()) pour le corps, sinon requête. Un corps optionnel exige un défaut None.

fastapi
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(
    item_id: int = Path(ge=1),
    q: Optional[str] = Query(default=None),
    item: Item = None,
):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result["q"] = q
    return result
05

Modèle de réponse

Bases de response_model

response_model filtre les données renvoyées aux seuls champs définis dans le modèle, même si vous renvoyez un objet avec des champs supplémentaires. C'est la façon standard de masquer les champs sensibles comme les mots de passe.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class User(BaseModel):
    username: str
    email: str
    hashed_password: str

class UserOut(BaseModel):
    username: str
    email: str

app = FastAPI()

@app.get("/users/me", response_model=UserOut)
def read_user():
    return User(username="bob", email="[email protected]", hashed_password="secret")

# response: {"username": "bob", "email": "[email protected]"}  (no password)

Exclure des champs

response_model_include et response_model_exclude permettent de whitelister ou blacklister des champs par route sans définir de nouveaux modèles. Passez un ensemble de noms de champs. Ils s'appliquent en plus du response_model.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    secret: str

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude={"secret"})
def read_item(id: int):
    return {"name": "Apple", "price": 0.5, "secret": "hidden"}

@app.get("/items", response_model=list[Item], response_model_include={"name", "price"})
def list_items():
    return [{"name": "Apple", "price": 0.5, "secret": "x"}]

Réponse en liste

Utilisez response_model=list[Model] (ou List[Model]) pour déclarer qu'un endpoint renvoie un tableau d'objets. FastAPI valide et sérialise chaque élément de la liste.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.get("/items", response_model=list[Item])
def list_items():
    return [
        {"name": "Apple", "price": 0.5},
        {"name": "Banana", "price": 0.3},
    ]

# response: [{"name": "Apple", "price": 0.5}, {"name": "Banana", "price": 0.3}]

Exclure non définis/défauts

exclude_unset omet les champs que le client n'a jamais envoyés (seuls les champs explicitement définis apparaissent). exclude_defaults omet les champs égaux à leur défaut ; exclude_none omet les champs None. Utile pour des réponses éparses.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float = 0.0
    tax: float = 0.0

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude_unset=True)
def read_item(id: int):
    return {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5}   (description, tax omitted)

# also: response_model_exclude_defaults=True
#       response_model_exclude_none=True

Réponse par alias

Field(alias=...) permet au JSON entrant d'utiliser un nom de clé différent de l'attribut Python. response_model_by_alias=True produit aussi la sortie avec l'alias. populate_by_name=True accepte aussi le nom d'attribut d'origine en entrée.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, Field

class Item(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    name: str = Field(alias="itemName")
    price: float

app = FastAPI()

@app.post("/items", response_model=Item, response_model_by_alias=True)
def create(item: Item):
    return item

# input:  {"itemName": "Apple", "price": 0.5}
# output: {"itemName": "Apple", "price": 0.5}

Réponse dict simple

Renvoyer un dict/list se sérialise automatiquement en JSON. Utilisez response_class pour changer le type de réponse par défaut (HTMLResponse, PlainTextResponse), ou renvoyez directement une sous-classe de Response pour un contrôle total.

fastapi
from fastapi import FastAPI
from fastapi.responses import JSONResponse, PlainTextResponse

app = FastAPI()

@app.get("/dict")
def dict_resp():
    return {"a": 1, "b": 2}      # auto JSON

@app.get("/text", response_class=PlainTextResponse)
def text_resp():
    return "plain text response"

@app.get("/raw")
def raw_resp():
    return JSONResponse(content={"a": 1}, status_code=200)
06

Formulaires et UploadFile

Données de formulaire

Form() déclare un paramètre parsé depuis application/x-www-form-urlencoded ou des données de formulaire multipart. On ne peut pas mélanger Form() avec un corps JSON (BaseModel) dans une même opération — choisissez un type de contenu.

fastapi
from fastapi import FastAPI, Form

app = FastAPI()

@app.post("/login")
def login(username: str = Form(), password: str = Form()):
    return {"username": username}

# Content-Type: application/x-www-form-urlencoded
# body: username=bob&password=secret

UploadFile de base

UploadFile est une représentation de fichier en flux avec .filename, .content_type, .read(), .write(), .close(). Utilisez 'await file.read()' dans async def. Pour les gros fichiers, préférez file.file (SpooledTemporaryFile) pour éviter de tout charger en mémoire.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    contents = await file.read()
    return {
        "filename": file.filename,
        "size": len(contents),
        "content_type": file.content_type,
    }

Plusieurs fichiers

Déclarez list[UploadFile] pour accepter plusieurs fichiers dans une requête. Chaque fichier est envoyé avec le même nom de champ. L'ordre des fichiers dans la liste suit l'ordre d'envoi.

fastapi
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/uploads")
async def upload_many(files: list[UploadFile]):
    return [
        {"filename": f.filename, "size": len(await f.read())}
        for f in files
    ]

# curl: curl -F "[email protected]" -F "[email protected]" http://localhost:8000/uploads

Fichier et formulaire ensemble

Form() et UploadFile (File()) se combinent dans un même endpoint car les deux utilisent multipart/form-data. On ne peut toujours pas les combiner avec un corps JSON BaseModel.

fastapi
from fastapi import FastAPI, UploadFile, File, Form

app = FastAPI()

@app.post("/items")
async def create_item(
    name: str = Form(),
    description: str = Form(),
    file: UploadFile = File(),
):
    return {
        "name": name,
        "description": description,
        "file": file.filename,
    }

Enregistrer le fichier envoyé

Pour les petits fichiers, shutil.copyfileobj envoie le SpooledTemporaryFile sur disque efficacement. Pour les très gros fichiers, lisez par tranches (ex. 1 Mo) pour garder la mémoire basse. Assainissez toujours file.filename pour éviter le path traversal.

fastapi
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/save")
async def save_file(file: UploadFile):
    dest = Path("uploads") / file.filename
    dest.parent.mkdir(exist_ok=True)
    with dest.open("wb") as buf:
        shutil.copyfileobj(file.file, buf)
    return {"saved_to": str(dest)}

# async alternative for large files:
# async with dest.open("wb") as buf:
#     while chunk := await file.read(1024 * 1024):
#         buf.write(chunk)

Métadonnées et taille de fichier

Validez file.content_type et la taille avant traitement. Après read(), le curseur est à la fin ; appelez 'await file.seek(0)' pour revenir au début si vous devez relire. Une vraie vérification de type devrait inspecter les magic bytes, pas seulement l'en-tête.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/validate")
async def validate(file: UploadFile = File(...)):
    # allowed types
    allowed = {"image/png", "image/jpeg"}
    if file.content_type not in allowed:
        return {"error": "unsupported type"}

    contents = await file.read()
    max_size = 5 * 1024 * 1024  # 5 MB
    if len(contents) > max_size:
        return {"error": "file too large"}

    await file.seek(0)  # rewind so later reads work
    return {"filename": file.filename, "size": len(contents)}
07

En-têtes et cookies

Paramètres d'en-tête

Header() déclare un paramètre lu depuis les en-têtes de requête. FastAPI convertit les underscores des noms Python en tirets (x_token -> X-Token). Mettez convert_underscores=False pour désactiver ce comportement.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/items")
def read_items(user_agent: str | None = Header(default=None)):
    return {"User-Agent": user_agent}

# Header names are case-insensitive; an underscore in the
# parameter (x_token) is converted to a hyphen (X-Token) automatically.
@app.get("/secure")
def secure(x_token: str = Header()):
    return {"x-token": x_token}

Paramètres de cookie

Cookie() lit une valeur depuis l'en-tête Cookie de la requête. Comme les paramètres de requête, les cookies sans défaut sont requis, et vous pouvez appliquer de la validation (min_length, max_length, etc.).

fastapi
from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/session")
def read_session(session_id: str | None = Cookie(default=None)):
    if session_id:
        return {"session_id": session_id}
    return {"message": "no session"}

# Reads the 'session_id' cookie from the Cookie header.

Définir un cookie dans la réponse

Injectez une Response et appelez set_cookie() pour écrire des cookies dans la réponse sortante. Utilisez httponly=True (bloque l'accès JS), secure=True (HTTPS uniquement) et samesite='lax'/'strict' pour atténuer le CSRF. Le corps de réponse est renvoyé normalement.

fastapi
from fastapi import FastAPI, Response

app = FastAPI()

@app.post("/login")
def login(response: Response):
    response.set_cookie(
        key="session_id",
        value="abc123",
        httponly=True,
        max_age=1800,
        secure=True,
        samesite="lax",
    )
    return {"message": "logged in"}

@app.post("/logout")
def logout(response: Response):
    response.delete_cookie("session_id")
    return {"message": "logged out"}

En-têtes de réponse personnalisés

Définissez des en-têtes sur une Response injectée pour les ajouter à la réponse JSON que construit FastAPI, ou passez headers= en renvoyant directement une sous-classe de Response. Les en-têtes personnalisés servent souvent aux infos de rate-limit et aux temps de traitement.

fastapi
from fastapi import FastAPI, Response
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/data")
def get_data(response: Response):
    response.headers["X-Process-Time"] = "0.05"
    response.headers["X-Custom-Header"] = "hello"
    return {"data": 1}

@app.get("/direct")
def direct():
    return JSONResponse(
        content={"data": 1},
        headers={"X-Source": "direct"},
    )

En-têtes standards

Les en-têtes courants comme Host, Accept, Authorization, If-None-Match sont accessibles via Header(). Pour Authorization, préférez les utilitaires de sécurité intégrés (HTTPBearer, OAuth2) qui gèrent le parsing et la doc OpenAPI pour vous.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/info")
def info(
    host: str | None = Header(default=None),
    accept: str | None = Header(default=None),
    authorization: str | None = Header(default=None),
    if_none_match: str | None = Header(default=None),
):
    return {"host": host, "accept": accept}

Valeurs d'en-tête dupliquées

Déclarer un type liste pour un paramètre Header collecte toutes les valeurs répétées de l'en-tête dans une liste. Utile pour des en-têtes comme Set-Cookie (réponse) ou tout en-tête personnalisé pouvant apparaître plusieurs fois.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/multi")
def multi(x_token: list[str] | None = Header(default=None)):
    return {"x_token": x_token}

# Request with:
#   X-Token: a
#   X-Token: b
# -> {"x_token": ["a", "b"]}
08

Injection de dépendances

Depends de base

Depends() injecte la valeur de retour d'une fonction dans votre opération de chemin. La logique partagée (pagination, parsing, sessions DB) vit à un seul endroit et se réutilise entre endpoints. Les paramètres de la dépendance sont aussi documentés dans OpenAPI.

fastapi
from fastapi import FastAPI, Depends

app = FastAPI()

def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items")
def list_items(commons: dict = Depends(common_params)):
    return commons

@app.get("/users")
def list_users(commons: dict = Depends(common_params)):
    return commons

Dépendances par classe

Une classe avec __init__ peut être une dépendance ; FastAPI l'appelle comme une fonction. Utilisez Depends(CommonQueryParams) ou le raccourci Depends() quand le paramètre est annoté avec la classe. L'instance est injectée.

fastapi
from fastapi import FastAPI, Depends

class CommonQueryParams:
    def __init__(self, q: str | None = None, skip: int = 0, limit: int = 10):
        self.q = q
        self.skip = skip
        self.limit = limit

app = FastAPI()

@app.get("/items")
def list_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
    return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}

# shorthand: commons = Depends() infers the type

Dépendances imbriquées

Les dépendances peuvent elles-mêmes dépendre d'autres dépendances, formant un graphe. FastAPI résout tout l'arbre, met en cache chaque résultat par requête et propage les exceptions. Idéal pour une auth en couches (token -> user -> permissions).

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def get_token(authorization: str = Header()):
    if not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="invalid header")
    return authorization.removeprefix("Bearer ")

def get_current_user(token: str = Depends(get_token)):
    if token != "admin-token":
        raise HTTPException(status_code=403, detail="forbidden")
    return {"username": "admin"}

app = FastAPI()

@app.get("/me")
def me(user: dict = Depends(get_current_user)):
    return user

Dépendances yield (nettoyage)

Un générateur de dépendance (yield) est parfait pour les ressources nécessitant un nettoyage : sessions DB, handles de fichiers, transactions. Le code après yield s'exécute comme finaliseur, même si la route lève une exception. Un seul yield par dépendance.

fastapi
from fastapi import FastAPI, Depends

def get_db():
    db = open_db_session()       # acquire resource
    try:
        yield db                 # injected into the route
    finally:
        db.close()               # always runs after the request

app = FastAPI()

@app.get("/items")
def list_items(db = Depends(get_db)):
    return db.query("SELECT * FROM items")

Dépendances globales

Passez dependencies=[...] à FastAPI() (ou à un APIRouter) pour les imposer à chaque route sans injecter leur valeur de retour. Utile pour une auth globale, un rate limiting ou la journalisation des requêtes.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "supersecret":
        raise HTTPException(status_code=400, detail="X-Token missing")

def verify_key(x_key: str = Header()):
    if x_key != "realkey":
        raise HTTPException(status_code=400, detail="X-Key missing")

# applied to every route in the app
app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])

@app.get("/items")
def list_items():
    return [{"item": "a"}]   # token & key already checked

Dépendances par route

Utilisez dependencies=[Depends(...)] sur un décorateur (ou un APIRouter) pour exiger une dépendance sur des routes précises sans utiliser sa valeur de retour. Les signatures de route restent propres tout en imposant les vérifications.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "secret":
        raise HTTPException(status_code=401, detail="bad token")

app = FastAPI()

@app.get("/public")
def public():
    return {"open": True}

@app.get("/private", dependencies=[Depends(verify_token)])
def private():
    return {"secret": "data"}
09

Sécurité (HTTPBasic / OAuth2 / JWT)

Auth HTTP Basic

HTTPBasic parse l'en-tête Authorization: Basic en username/password. Utilisez secrets.compare_digest (pas ==) pour prévenir les attaques temporelles. Renvoyez toujours 401 avec WWW-Authenticate: Basic pour que les navigateurs demandent les identifiants.

fastapi
import secrets
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

security = HTTPBasic()
app = FastAPI()

def get_current_user(credentials: HTTPBasicCredentials = Depends(security)):
    correct_user = secrets.compare_digest(credentials.username, "admin")
    correct_pass = secrets.compare_digest(credentials.password, "secret")
    if not (correct_user and correct_pass):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username

@app.get("/profile")
def profile(user: str = Depends(get_current_user)):
    return {"user": user}

OAuth2 Password Bearer

OAuth2PasswordBearer déclare que les routes attendent un token Bearer ; la dépendance l'extrait de l'en-tête Authorization. tokenUrl indique à l'UI de doc où envoyer les identifiants. Le token lui-même n'est qu'une chaîne tant que vous ne le validez pas.

fastapi
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()

@app.get("/me")
def me(token: str = Depends(oauth2_scheme)):
    return {"token": token}

# client POSTs username+password to /token, receives an access token,
# then sends it as: Authorization: Bearer <token>

Créer un token JWT

Utilisez python-jose (ou PyJWT) pour signer les tokens. La claim 'sub' (subject) porte conventionnellement le username ou l'id utilisateur, et 'exp' fixe l'expiration. Gardez SECRET_KEY longue, aléatoire et chargée depuis l'environnement — ne la commitez jamais.

fastapi
from datetime import datetime, timedelta, timezone
from jose import jwt

SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def create_access_token(data: dict, expires_minutes: int = 30) -> str:
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + timedelta(minutes=expires_minutes)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

# token = create_access_token({"sub": "alice"})
# -> eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Décoder un token JWT

jwt.decode vérifie la signature et la claim 'exp' automatiquement, en levant JWTError en cas d'échec. Mappez la dépendance à un 401 avec WWW-Authenticate: Bearer pour que les clients sachent fournir un token valide.

fastapi
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def get_current_user(token: str = Depends(oauth2_scheme)) -> str:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str | None = payload.get("sub")
        if username is None:
            raise credentials_exception
        return username
    except JWTError:
        raise credentials_exception

credentials_exception = HTTPException(
    status_code=status.HTTP_401_UNAUTHORIZED,
    detail="Could not validate credentials",
    headers={"WWW-Authenticate": "Bearer"},
)

Hachage des mots de passe

Ne stockez jamais les mots de passe en clair. passlib avec bcrypt (ou argon2) gère salage et hachage. verify() compare une entrée en clair à un hash stocké. pip install passlib[bcrypt] pour obtenir le backend bcrypt.

fastapi
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def hash_password(plain: str) -> str:
    return pwd_context.hash(plain)

def verify_password(plain: str, hashed: str) -> bool:
    return pwd_context.verify(plain, hashed)

# usage when issuing tokens:
def authenticate_user(username: str, password: str):
    user = fake_db.get(username)
    if not user or not verify_password(password, user.hashed_password):
        return False
    return user

Flux de connexion OAuth2

OAuth2PasswordRequestForm lit username/password depuis un POST encodé en formulaire (le flux OAuth2 password standard). Renvoyez access_token et token_type: 'bearer'. Cet endpoint est celui vers lequel pointe tokenUrl de OAuth2PasswordBearer.

fastapi
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm

app = FastAPI()

@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form.username, form.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
        )
    token = create_access_token({"sub": user.username})
    return {"access_token": token, "token_type": "bearer"}

# OAuth2PasswordRequestForm parses username+password from form data
# and powers the 'Authorize' button in the Swagger UI.
10

Middleware

Ajouter un middleware

@app.middleware('http') enregistre une fonction qui enveloppe chaque requête. Elle doit await call_next(request) pour obtenir la réponse, puis peut l'inspecter ou la modifier avant de la renvoyer. Le middleware s'exécute pour toutes les routes.

fastapi
import time
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_process_time(request: Request, call_next):
    start = time.perf_counter()
    response = await call_next(request)
    duration = time.perf_counter() - start
    response.headers["X-Process-Time"] = f"{duration:.4f}"
    return response

Middleware d'en-têtes personnalisés

Le middleware est le bon endroit pour attacher des en-têtes devant figurer sur chaque réponse (en-têtes de sécurité, bannière serveur, IDs de traçage). Modifiez l'objet réponse après avoir await call_next.

fastapi
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_banner(request: Request, call_next):
    response = await call_next(request)
    response.headers["X-Powered-By"] = "FastAPI"
    response.headers["X-Frame-Options"] = "DENY"
    return response

# every response now carries these headers

BaseHTTPMiddleware

Pour un middleware réutilisable et configurable, héritez de BaseHTTPMiddleware et enregistrez-le avec app.add_middleware(MyMiddleware, **options). C'est aussi ainsi qu'on ajoute les middlewares intégrés CORS, GZip et TrustedHost.

fastapi
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Request

class TimingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        start = time.perf_counter()
        response = await call_next(request)
        response.headers["X-Duration"] = str(time.perf_counter() - start)
        return response

app = FastAPI()
app.add_middleware(TimingMiddleware)

# class-based middleware is reusable and configurable

Redirection HTTPS

HTTPSRedirectMiddleware renvoie une redirection 308 vers la version HTTPS de toute requête HTTP. Utilisez-le derrière un load balancer qui termine le TLS, pour garantir que les clients passent à une connexion sécurisée.

fastapi
from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware

app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)

# all HTTP requests are redirected to HTTPS (308)

Hôte de confiance

TrustedHostMiddleware rejette les requêtes dont l'en-tête Host n'est pas dans la liste autorisée, prévenant les attaques par injection d'en-tête Host. Les wildcards comme '*.example.com' sont pris en charge. Incluez toujours 'localhost' pour le développement local.

fastapi
from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["example.com", "*.example.com", "localhost"],
)

# requests with a disallowed Host header get a 400 response

Ordre des middleware

Starlette exécute les middleware en ordre LIFO pour les requêtes entrantes : le dernier ajouté tourne en premier. Ajoutez CORS tôt (pour que le preflight fonctionne) et GZip après. Retenez-le quand vous déboguez pourquoi un en-tête posé par un middleware n'est pas vu par un autre.

fastapi
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Middleware runs in REVERSE order of registration for requests,
# and in registration order for responses.
app.add_middleware(GZipMiddleware, minimum_size=1000)
app.add_middleware(CORSMiddleware, allow_origins=["*"])

# request flow:  CORS -> GZip -> route
# response flow: route -> GZip -> CORS
11

CORS

Configuration de CORSMiddleware

CORSMiddleware gère le preflight CORS (OPTIONS) et ajoute les en-têtes Access-Control-*. allow_origins doit lister les origines exactement autorisées ; en production, utilisez une liste d'URLs précises plutôt que ['*'].

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com", "https://www.example.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/api/data")
def data():
    return {"data": 1}

Autoriser toutes les origines (dev uniquement)

allow_origins=['*'] autorise toute origine mais ne peut pas se combiner avec allow_credentials=True (les navigateurs le rejettent). Réservez-le aux API totalement publiques en développement ; en production, énumérez les vraies origines.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
    # allow_credentials=True CANNOT be combined with allow_origins=["*"]
)

Autoriser les credentials

allow_credentials=True permet au navigateur d'envoyer cookies et en-têtes Authorization en cross-origin. Cela exige des origines spécifiques (jamais '*'). Le navigateur définit Access-Control-Allow-Credentials: true sur les réponses.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_credentials=True,    # send cookies / Authorization
    allow_methods=["GET", "POST"],
    allow_headers=["Authorization", "Content-Type"],
)

# needed when the frontend sends cookies or credentials with requests

Méthodes et en-têtes autorisés

allow_methods/allow_headers restreignent ce que le navigateur peut envoyer. expose_headers liste les en-têtes de réponse que le JavaScript frontal peut lire (sinon les navigateurs masquent les en-têtes personnalisés). Les réponses de preflight sont mises en cache par le navigateur.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
    allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
    expose_headers=["X-Total-Count", "X-Process-Time"],
)

# expose_headers lets the frontend JS read these response headers

Requêtes de preflight

Pour les requêtes « non simples » (ex. en-têtes personnalisés, PUT/DELETE, contenu JSON), le navigateur envoie un preflight OPTIONS. CORSMiddleware intercepte OPTIONS et répond avec les méthodes/en-têtes autorisés. max_age contrôle la durée de mise en cache de cette réponse par le navigateur.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["*"],
    allow_headers=["*"],
    max_age=600,   # browser caches preflight result for 600s
)

# Browser sends OPTIONS preflight for non-simple requests;
# CORSMiddleware answers automatically with the right headers.

Validation dynamique des origines

Pour des listes dynamiques, utilisez allow_origin_regex (correspond à l'Origin de la requête) au lieu d'une liste statique. Pratique quand les origines valides suivent un motif (ex. tout sous-domaine de example.com).

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

VALID_DOMAINS = {"example.com", "staging.example.com"}

def origin_check(origin: str) -> str | None:
    if origin and origin.replace("https://", "").replace("http://", "") in VALID_DOMAINS:
        return origin
    return None

app.add_middleware(
    CORSMiddleware,
    allow_origin_regex=r"https://.*\.example\.com",
    allow_methods=["*"],
    allow_headers=["*"],
)
12

Gestion des exceptions

Lever HTTPException

Lever HTTPException n'importe où dans une route ou une dépendance court-circuite et renvoie une réponse d'erreur. detail peut être une chaîne, un dict ou une liste — il devient le champ JSON 'detail'. headers ajoute optionnellement des en-têtes de réponse.

fastapi
from fastapi import FastAPI, HTTPException, status

app = FastAPI()

items = {1: "Apple", 2: "Banana"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id not in items:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
            headers={"X-Error": "missing"},
        )
    return {"item": items[item_id]}

Exception personnalisée

Enregistrez un handler avec @app.exception_handler(MyException) pour convertir n'importe quelle exception personnalisée en réponse HTTP. Le handler reçoit la requête et l'exception. Cela centralise le formatage des erreurs du domaine de votre app.

fastapi
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name

app = FastAPI()

@app.exception_handler(UnicornException)
async def unicorn_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops, {exc.name} did it again"},
    )

@app.get("/unicorns/{name}")
def read_unicorn(name: str):
    if name == "yolo":
        raise UnicornException(name=name)
    return {"name": name}

Surcharger l'erreur de validation

RequestValidationError se lève quand l'entrée échoue à la validation Pydantic. Surchargez son handler avec @app.exception_handler(RequestValidationError) pour personnaliser la forme de la réponse 422, ex. pour coller à une enveloppe d'erreur d'entreprise.

fastapi
from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={
            "success": False,
            "errors": exc.errors(),
            "body": exc.body,
        },
    )

Surcharger le handler HTTPException

Surchargez le handler HTTPException par défaut pour imposer une forme d'erreur JSON cohérente à toutes les HTTPException levées. Importez la classe comme fastapi.exceptions.HTTPException (celle utilisée par raise) quand vous re-liez son handler.

fastapi
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException as FastAPIHTTPException

app = FastAPI()

@app.exception_handler(FastAPIHTTPException)
async def custom_http_handler(request, exc: FastAPIHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "success": False,
            "status": exc.status_code,
            "message": exc.detail,
        },
        headers=exc.headers,
    )

Codes de statut courants

Le module status fournit des constantes nommées pour tous les codes de statut HTTP, évitant les nombres magiques. 200 (défaut GET), 201 (créé), 204 (sans contenu), 422 (validation) sont les plus courants dans les apps FastAPI.

fastapi
from fastapi import FastAPI, status

app = FastAPI()

@app.get("/ok", status_code=status.HTTP_200_OK)
def ok(): return {"ok": True}

@app.post("/create", status_code=status.HTTP_201_CREATED)
def create(): return {"id": 1}

@app.get("/no-content", status_code=status.HTTP_204_NO_CONTENT)
def no_content(): return None

@app.get("/not-found")
def missing():
    # raise HTTPException(status.HTTP_404_NOT_FOUND, "nope")
    ...

# Other common: 400 BAD_REQUEST, 401 UNAUTHORIZED,
# 403 FORBIDDEN, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 500 INTERNAL_SERVER_ERROR

Handler d'exception générique

Enregistrer un handler pour la classe de base Exception attrape tout ce qui n'est pas déjà géré, empêchant les piles d'erreurs de fuiter vers les clients. Journalisez toujours la pile complète côté serveur ; renvoyez un 500 générique au client.

fastapi
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

logger = logging.getLogger("uvicorn.error")
app = FastAPI()

@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
    logger.exception("Unhandled error on %s", request.url.path)
    return JSONResponse(
        status_code=500,
        content={"detail": "Internal Server Error"},
    )

@app.get("/boom")
def boom():
    raise RuntimeError("something exploded")
13

Tâches en arrière-plan

BackgroundTasks de base

BackgroundTasks exécute des fonctions après l'envoi de la réponse — parfait pour du travail fire-and-forget comme le logging, les emails ou l'invalidation de cache. add_task planifie une fonction (et ses arguments) sans bloquer la réponse.

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message: str):
    with open("log.txt", "a") as f:
        f.write(message + "\n")

@app.post("/send")
def send_notification(background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, "notification sent")
    return {"message": "notification queued"}

Plusieurs tâches

Ajoutez autant de tâches que voulu ; elles s'exécutent séquentiellement dans l'ordre d'ajout, après le renvoi de la réponse. Comme elles tournent dans le même processus, gardez-les rapides et non bloquantes, ou passez à une vraie file (Celery, RQ, Dramatiq).

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def send_email(to: str, subject: str): ...
def update_cache(key: str): ...
def notify_slack(msg: str): ...

@app.post("/signup")
def signup(background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, "[email protected]", "Welcome")
    background_tasks.add_task(update_cache, "user_count")
    background_tasks.add_task(notify_slack, "new signup")
    return {"status": "ok"}

Tâche avec dépendances

BackgroundTasks s'injecte comme n'importe quelle dépendance. La fonction de tâche peut recevoir des valeurs (comme une session DB) capturées au moment de la requête. Notez que les ressources yieldées/fermées des dépendances se ferment après la fin des tâches, puisque les tâches tournent dans la portée du cycle de vie de la requête.

fastapi
from fastapi import FastAPI, BackgroundTasks, Depends

app = FastAPI()

def get_db_session():
    db = "session"
    yield db

def write_log(db, message: str):
    print(db, message)

@app.get("/items")
def list_items(background_tasks: BackgroundTasks, db = Depends(get_db_session)):
    background_tasks.add_task(write_log, db, "list called")
    return {"items": []}

Fonction de tâche asynchrone

Les fonctions de tâches en arrière-plan peuvent être synchrones (exécutées dans un threadpool) ou asynchrones (attendues sur la boucle d'événements). Utilisez des tâches async pour le travail lié aux E/S qui utilise lui-même des bibliothèques asynchrones, et des tâches sync pour le travail CPU/bloquant.

fastapi
from fastapi import FastAPI, BackgroundTasks
import httpx

app = FastAPI()

async def fetch_url(url: str):
    async with httpx.AsyncClient() as client:
        r = await client.get(url)
        return r.status_code

@app.post("/webhook")
def webhook(url: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(fetch_url, url)
    return {"queued": url}

Background vs Celery

Utilisez BackgroundTasks pour du travail léger, non critique, qu'on peut perdre au redémarrage. Pour des jobs qui doivent survivre aux crashs, réessayer ou s'étendre sur plusieurs machines, utilisez une vraie file de tâches (Celery, RQ, Dramatiq, Arq) avec un broker comme Redis ou RabbitMQ.

fastapi
# BackgroundTasks: in-process, no broker, lost if process crashes
@app.post("/quick")
def quick(tasks: BackgroundTasks):
    tasks.add_task(small_job)
    return {"ok": True}

# Celery/RQ/Dramatiq: separate workers, persistent, retryable
# from celery import Celery
# @celery.task
# def big_job(payload): ...
#
# @app.post("/heavy")
# def heavy(payload: dict):
#     big_job.delay(payload)
#     return {"queued": True}

Exemple d'envoi d'email

L'envoi d'email est le cas d'usage classique de BackgroundTasks : c'est lent et l'utilisateur ne devrait pas attendre. La réponse revient immédiatement pendant que l'email part ensuite. Pour de gros volumes, préférez une file et un SDK de service email avec reprises.

fastapi
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel, EmailStr

class Message(BaseModel):
    to: EmailStr
    subject: str
    body: str

app = FastAPI()

def send_email(to: str, subject: str, body: str):
    # smtplib or your provider's SDK
    import smtplib
    with smtplib.SMTP("localhost") as s:
        s.sendmail("[email protected]", to, f"Subject: {subject}\n\n{body}")

@app.post("/contact")
def contact(msg: Message, tasks: BackgroundTasks):
    tasks.add_task(send_email, msg.to, msg.subject, msg.body)
    return {"status": "queued", "to": msg.to}
14

WebSocket

WebSocket de base

Utilisez @app.websocket() pour définir un endpoint WebSocket. Vous devez accept() la connexion avant d'envoyer/recevoir. La fonction boucle typiquement en lisant des messages ; receive_text/receive_bytes/receive_json attendent tous des données du client.

fastapi
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        data = await ws.receive_text()
        await ws.send_text(f"echo: {data}")

# client (browser):
# const ws = new WebSocket("ws://localhost:8000/ws");
# ws.onmessage = (e) => console.log(e.data);

Envoyer du JSON

send_json() et receive_json() gèrent la sérialisation pour vous, en échangeant des objets JSON sur le socket. Pour des données binaires, utilisez send_bytes/receive_bytes. Chaque send/receive est une frame distincte du WebSocket.

fastapi
import json
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        msg = await ws.receive_json()
        await ws.send_json({"reply": msg.get("text", "").upper()})

# send_text / send_bytes / send_json helpers are available

Fermeture du WebSocket

WebSocketDisconnect se lève quand le client ferme la connexion — attrapez-le pour nettoyer. Appelez ws.close(code=1000) pour une fermeture normale ; codes courants : 1000 (normal), 1008 (violation de politique), 1011 (erreur serveur).

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            if data == "quit":
                await ws.close(code=1000)
                break
            await ws.send_text(data)
    except WebSocketDisconnect:
        print("client disconnected")

Gestionnaire de connexions

Un ConnectionManager suit les sockets actifs pour diffuser à tous les clients connectés (ex. une salle de chat). Retirez toujours le socket à la déconnexion pour ne pas envoyer à des connexions fermées et garder la mémoire bornée.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

class ConnectionManager:
    def __init__(self):
        self.active: list[WebSocket] = []

    async def connect(self, ws: WebSocket):
        await ws.accept()
        self.active.append(ws)

    def disconnect(self, ws: WebSocket):
        self.active.remove(ws)

    async def broadcast(self, message: str):
        for ws in self.active:
            await ws.send_text(message)

manager = ConnectionManager()
app = FastAPI()

@app.websocket("/chat")
async def chat(ws: WebSocket):
    await manager.connect(ws)
    try:
        while True:
            msg = await ws.receive_text()
            await manager.broadcast(msg)
    except WebSocketDisconnect:
        manager.disconnect(ws)

Auth WebSocket via paramètre de requête

Les navigateurs ne peuvent pas définir d'en-têtes personnalisés sur les connexions WebSocket, donc les tokens d'auth passent couramment en paramètres de requête (ou cookies). Validez avant d'appeler accept(), et fermez avec le code 1008 (violation de politique) si non autorisé.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException

app = FastAPI()

async def authenticate(token: str) -> str:
    if token != "secret":
        raise HTTPException(status_code=401)
    return "alice"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    token = ws.query_params.get("token")
    if not token:
        await ws.close(code=1008)
        return
    user = await authenticate(token)
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            await ws.send_text(f"{user}: {data}")
    except WebSocketDisconnect:
        pass

WebSocket avec dépendances

Les dépendances s'utilisent dans les endpoints WebSocket comme dans les routes HTTP, mais seules les dépendances lisant la poignée de main initiale (en-têtes, paramètres de requête, cookies) ont du sens — il n'y a pas de corps. Injectez-les via Depends() comme d'habitude.

fastapi
from fastapi import FastAPI, WebSocket, Depends, Header

app = FastAPI()

def token_validator(token: str = Header(default="")):
    # for WS, headers come from the initial HTTP handshake
    return token == "valid"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, valid: bool = Depends(token_validator)):
    if not valid:
        await ws.close(code=1008)
        return
    await ws.accept()
    while True:
        msg = await ws.receive_text()
        await ws.send_text(msg)
15

Base de données (SQLAlchemy)

Configuration SQLAlchemy

create_engine met en place le pool de connexions ; SessionLocal est une factory de sessions ; Base est la base déclarative des modèles. Pour SQLite avec FastAPI, mettez check_same_thread=False car les requêtes peuvent tourner dans des threads différents.

fastapi
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"
# postgresql: "postgresql://user:pass@localhost:5432/dbname"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    connect_args={"check_same_thread": False},  # sqlite only
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()

Dépendance de session

Une dépendance yield est la façon canonique de fournir une session DB : chaque requête reçoit une session fraîche, fermée dans le bloc finally. Cela garantit le nettoyage même si la route lève une exception.

fastapi
from fastapi import Depends
from sqlalchemy.orm import Session

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/items")
def list_items(db: Session = Depends(get_db)):
    return db.query(Item).all()

# each request gets its own session, closed automatically afterward

Définition de modèle

Définissez les tables comme modèles ORM SQLAlchemy héritant de Base. Utilisez Alembic pour les migrations de schéma en production plutôt que create_all(). Les colonnes peuvent être indexées, nullables, et avoir des défauts appliqués au niveau base ou Python.

fastapi
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base

Base = declarative_base()

class Item(Base):
    __tablename__ = "items"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True, nullable=False)
    price = Column(Integer, default=0)
    in_stock = Column(Boolean, default=True)

# create tables (for dev; use Alembic migrations in prod)
Base.metadata.create_all(bind=engine)

Créer un enregistrement

add() met en attente une nouvelle ligne, commit() l'écrit en base, et refresh() recharge l'instance avec les valeurs générées par le serveur (comme l'id auto-incrémenté). Enveloppez plusieurs écritures dans une transaction et commitez une fois à la fin.

fastapi
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session

app = FastAPI()

@app.post("/items", status_code=201)
def create_item(payload: ItemCreate, db: Session = Depends(get_db)):
    item = Item(name=payload.name, price=payload.price)
    db.add(item)
    db.commit()
    db.refresh(item)        # load generated id
    return item

Requêter des enregistrements

db.query(Model) démarre une requête ; .filter() applique les conditions WHERE, .offset()/.limit() paginent, .first() renvoie une ligne ou None, .all() une liste. Utilisez .filter_by(name=x) pour des conditions d'égalité simples.

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
    return db.query(Item).offset(skip).limit(limit).all()

@app.get("/items/{item_id}")
def get_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

Mise à jour et suppression

Pour les mises à jour partielles, itérez model_dump(exclude_unset=True) pour que seuls les champs fournis changent. delete() met en attente la suppression ; commit() la finalise. Renvoyez 204 No Content pour un DELETE réussi.

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    for k, v in payload.model_dump(exclude_unset=True).items():
        setattr(item, k, v)
    db.commit()
    db.refresh(item)
    return item

@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if item:
        db.delete(item)
        db.commit()
16

Base de données (Tortoise ORM)

Configuration Tortoise

Tortoise ORM est natif asynchrone, s'accordant bien avec FastAPI. Initialisez-le au démarrage avec db_url et le(s) module(s) contenant vos modèles. generate_schemas() convient en dev ; utilisez Aerich pour les migrations en production. Préférez le handler lifespan à on_event dans le code neuf.

fastapi
from fastapi import FastAPI
from tortoise import Tortoise

app = FastAPI()

async def init():
    await Tortoise.init(
        db_url="sqlite://db.sqlite3",
        modules={"models": ["app.models"]},
    )
    await Tortoise.generate_schemas()

@app.on_event("startup")
async def startup():
    await init()

@app.on_event("shutdown")
async def shutdown():
    await Tortoise.close_connections()

Définition de modèle

Les modèles Tortoise héritent de Model et déclarent les champs via tortoise.fields. Les types de champs correspondent aux types de colonnes DB. Fixez le nom de table dans la classe Meta interne. Les relations utilisent ForeignKeyField, ManyToManyField, etc.

fastapi
from tortoise import fields
from tortoise.models import Model

class Item(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=100)
    price = fields.FloatField(default=0.0)
    created_at = fields.DatetimeField(auto_now_add=True)

    class Meta:
        table = "items"

    def __str__(self):
        return self.name

Créer un enregistrement

Item.create() est une coroutine qui insère et renvoie la nouvelle ligne. Pour renvoyer une réponse Pydantic, construisez un BaseModel avec from_tortoise_orm() (via tortoise.contrib.pydantic) pour que Tortoise sérialise correctement les relations chargées async.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel
from .models import Item

app = FastAPI()

class ItemIn(BaseModel):
    name: str
    price: float

@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(payload: ItemIn):
    item = await Item.create(name=payload.name, price=payload.price)
    return await ItemOut.from_tortoise_orm(item)

Requête asynchrone

Les requêtes Tortoise s'attendent : .all() renvoie un queryset, .filter() ajoute des conditions, .get_or_none() récupère une ligne ou None, .first() le premier match. Évitez .get() sauf si vous attendez exactement une ligne (il lève si introuvable).

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
    return await Item.all().offset(skip).limit(limit)

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

Mise à jour et suppression

Modifiez les attributs du modèle puis await save() pour mettre à jour une ligne, ou await Item.filter(id=...).update(name=x) pour des mises à jour en masse. await item.delete() retire la ligne. Chaque méthode est une coroutine et doit être attendue.

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    item.name = name
    await item.save()
    return item

@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if item:
        await item.delete()

Schémas Pydantic Tortoise

tortoise.contrib.pydantic génère des modèles Pydantic directement depuis les modèles Tortoise, vous ne maintenez donc pas deux schémas. Utilisez pydantic_model_creator pour un objet unique et pydantic_queryset_creator pour une réponse en liste.

fastapi
from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
from .models import Item

ItemOut = pydantic_model_creator(Item, name="ItemOut")
ItemList = pydantic_queryset_creator(Item)

@app.get("/items", response_model=ItemList)
async def list_items():
    return await Item.all()

# auto-generates a Pydantic model from the Tortoise model,
# including types and docstrings.
17

Tests (TestClient)

TestClient de base

TestClient enveloppe votre app et permet des requêtes dans le processus (pas de vrai socket). Il repose sur httpx et fonctionne avec pytest sans configuration. Importez la même instance d'app que celle exécutée en production.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"Hello": "World"}

# TestClient is based on httpx; no network is involved —
# it calls the ASGI app directly in-process.

Tester GET et POST

Passez json= pour les corps JSON, params= pour les paramètres de requête, headers= pour les en-têtes, et files= pour les uploads multipart. Les échecs de validation renvoient 422 — affirmez sur status_code et la structure du 'detail' d'erreur.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_create_item():
    response = client.post(
        "/items",
        json={"name": "Apple", "price": 0.5},
    )
    assert response.status_code == 201
    assert response.json()["name"] == "Apple"

def test_validation_error():
    response = client.post("/items", json={"name": "Apple"})  # missing price
    assert response.status_code == 422

Fixture pytest

Une fixture pytest renvoyant un TestClient évite la répétition et donne à chaque test un client frais. Pour les tests avec base de données, ajoutez une fixture qui crée/supprime les tables ou utilise un rollback de transaction par test pour les isoler.

fastapi
import pytest
from fastapi.testclient import TestClient
from main import app

@pytest.fixture
def client():
    return TestClient(app)

def test_read(client):
    r = client.get("/items")
    assert r.status_code == 200

def test_create(client):
    r = client.post("/items", json={"name": "X"})
    assert r.status_code == 201

# run: pytest -v

Surcharger les dépendances

app.dependency_overrides remplace une dépendance (comme la vraie session DB ou l'auth) par un mock/fake pendant les tests, sans toucher aux routes. C'est la façon canonique de tester les endpoints isolés des services externes. Videz-le après les tests.

fastapi
from fastapi.testclient import TestClient
from main import app, get_db

def get_test_db():
    # return a test session or mock
    yield FakeSession()

app.dependency_overrides[get_db] = get_test_db

client = TestClient(app)

def test_items():
    r = client.get("/items")
    assert r.status_code == 200

# restore afterwards:
app.dependency_overrides.clear()

Tester l'authentification

OAuth2PasswordRequestForm attend des données encodées en formulaire (data=, pas json=). Utilisez le token renvoyé dans l'en-tête Authorization: Bearer pour les requêtes protégées suivantes. Pour contourner entièrement l'auth, surchargez plutôt la dépendance get_current_user.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def get_token():
    r = client.post(
        "/token",
        data={"username": "admin", "password": "secret"},
    )
    return r.json()["access_token"]

def test_protected():
    token = get_token()
    r = client.get(
        "/me",
        headers={"Authorization": f"Bearer {token}"},
    )
    assert r.status_code == 200
    assert r.json()["username"] == "admin"

Tester le WebSocket

TestClient.websocket_connect() ouvre un WebSocket dans un gestionnaire de contexte. Utilisez send_text/receive_text (et les variantes json/bytes) pour échanger des messages. Recevoir sur une connexion fermée lève WebSocketDisconnect.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_websocket():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("hello")
        data = ws.receive_text()
        assert data == "echo: hello"

def test_websocket_close():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("quit")
        # the server closes the connection
18

Documentation OpenAPI

Swagger UI

FastAPI génère automatiquement une Swagger UI interactive à /docs à partir de vos routes, types et docstrings. Réglez title/description/version sur l'app, et ajoutez une docstring ou summary/description à chaque route pour enrichir l'UI.

fastapi
from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="Sample API with auto docs",
    version="1.0.0",
)

@app.get("/items", summary="List items", description="Returns all items")
def list_items():
    """Get every item in the catalog."""
    return [{"id": 1}]

# interactive docs at: http://localhost:8000/docs

ReDoc

ReDoc à /redoc est une alternative en lecture seule, centrée sur la documentation. Le schéma OpenAPI brut vit à /openapi.json et peut alimenter d'autres outils. Désactivez la doc avec docs_url=None, redoc_url=None, openapi_url=None (ex. en production).

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"hello": "world"}

# ReDoc (alternative docs UI) at: http://localhost:8000/redoc
# raw OpenAPI JSON at: http://localhost:8000/openapi.json

# disable docs entirely:
# app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

Tags et regroupement

Les tags regroupent les routes dans l'UI de doc. Déclarez les métadonnées de tags (name, description, externalDocs) dans openapi_tags pour que le groupe apparaisse même avant toute route qui l'utilise. Mettez deprecated=True pour marquer un endpoint comme déprécié dans la doc.

fastapi
from fastapi import FastAPI

app = FastAPI(openapi_tags=[
    {"name": "users", "description": "User management"},
    {"name": "items", "description": "Item operations"},
])

@app.get("/users", tags=["users"])
def list_users(): ...

@app.post("/items", tags=["items"])
def create_item(): ...

@app.get("/items/{id}", tags=["items"], deprecated=True)
def get_item(id: int): ...

Métadonnées de route

Les décorateurs acceptent des métadonnées qui alimentent OpenAPI : summary (titre court), description (texte long), response_description, tags, deprecated et status_code. Une docstring sert de description si vous n'en passez pas explicitement.

fastapi
from fastapi import FastAPI, status
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.post(
    "/items",
    response_model=Item,
    status_code=status.HTTP_201_CREATED,
    summary="Create an item",
    description="Creates a new item and returns it.",
    tags=["items"],
    response_description="The created item",
)
def create_item(item: Item):
    """Create endpoint docstring — also shown in docs."""
    return item

Exemples de champs

Field(examples=[...]) et Body(examples=[...]) ajoutent des charges utiles d'exemple au « Try it out » de Swagger UI et au menu déroulant d'exemples. Les exemples de Body peuvent inclure plusieurs cas avec des résumés pour montrer des entrées valides et invalides.

fastapi
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body

class Item(BaseModel):
    name: str = Field(examples=["Apple"])
    price: float = Field(examples=[0.5], gt=0)

app = FastAPI()

@app.post("/items")
def create_item(item: Item):
    return item

@app.post("/manual")
def manual(
    item: Item = Body(
        examples=[
            {"summary": "valid", "value": {"name": "Apple", "price": 0.5}},
            {"summary": "invalid", "value": {"name": "Apple", "price": -1}},
        ],
    ),
):
    return item

Schéma OpenAPI personnalisé

Surchargez app.openapi pour personnaliser le schéma généré — ajouter un logo, des métadonnées supplémentaires, ou retirer/transformer des opérations. Mettez le résultat en cache dans app.openapi_schema pour qu'il ne soit généré qu'une fois. Le schéma est ce que sert /openapi.json.

fastapi
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title="Custom API",
        version="2.0.0",
        routes=app.routes,
    )
    schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
    app.openapi_schema = schema
    return schema

app.openapi = custom_openapi
19

Déploiement (Uvicorn / Gunicorn)

Uvicorn en production

En production, exécutez Uvicorn derrière un reverse proxy (Nginx, Caddy, un load balancer cloud). Utilisez --proxy-headers pour que l'app voie la vraie IP/hôte du client depuis X-Forwarded-For/X-Forwarded-Proto. Évitez --reload en production.

fastapi
# Run directly with uvicorn (single worker)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1

# Recommended: behind a reverse proxy (nginx) on port 8000
# Use --proxy-headers so X-Forwarded-* is trusted
uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'

Gunicorn avec workers Uvicorn

Gunicorn gère plusieurs processus workers Uvicorn, offrant des recharges gracieuses, des redémarrages après crash et un scaling pré-fork. Utilisez la classe UvicornWorker. Commencez avec workers à (2 * cœurs CPU + 1), puis benchmarkez.

fastapi
# install the uvicorn worker class
pip install "uvicorn[standard]" gunicorn

# run 4 worker processes managed by gunicorn
gunicorn main:app \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    -b 0.0.0.0:8000 \
    --timeout 120

# -w workers (commonly 2*CPU+1), -k worker class

Déploiement Docker

Une image de base Python slim garde l'image légère. Installez les dépendances avant de copier le code pour exploiter le cache de couches de Docker. Exécutez avec des workers gunicorn+uvicorn dans le conteneur, et exposez le port 8000 à l'hôte ou à l'orchestrateur.

fastapi
# Dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["gunicorn", "main:app", "-w", "4", \
     "-k", "uvicorn.workers.UvicornWorker", \
     "-b", "0.0.0.0:8000"]

# build & run:
# docker build -t myapi .
# docker run -p 8000:8000 myapi

Configuration par environnement

pydantic-settings (ex-pydantic.BaseSettings) charge la config depuis les variables d'environnement et les fichiers .env avec validation de type. La même image peut ainsi tourner dans différents environnements (dev/staging/prod) en changeant simplement les variables.

fastapi
import os
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str = "sqlite:///./app.db"
    secret_key: str = "change-me"
    debug: bool = False
    allowed_origins: list[str] = ["http://localhost:3000"]

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

# .env file:
# DATABASE_URL=postgresql://user:pass@db:5432/app
# SECRET_KEY=long-random-string
# DEBUG=false

Reverse proxy Nginx

Nginx termine le HTTP(S) et transmet à Uvicorn sur localhost:8000. Réglez les en-têtes X-Forwarded-* (et utilisez --proxy-headers sur Uvicorn) pour que l'app voie la vraie IP et le schéma du client. Les lignes Upgrade/Connection activent le support WebSocket.

fastapi
# /etc/nginx/conf.d/api.conf
server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Scaling et concurrence

Deux axes de montée en charge : plus de processus workers Uvicorn par machine (lié au CPU), et plus de machines derrière un load balancer (horizontal). Pour les apps asynchrones, la boucle d'événements gère de nombreuses requêtes I/O concurrentes par worker. Ajoutez un endpoint /health pour que les orchestrateurs (k8s, ECS) sondent l'état de vie.

fastapi
# Workers = process count (vertical scaling); pick ~2*CPU
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

# Inside async app: concurrency is cooperative via the event loop.
# CPU-bound work blocks it — offload to a threadpool or task queue.

# Horizontal scaling: run several containers behind a load balancer.
# Use a shared store (Redis) for session state and rate limits.

# Health check endpoint for the balancer:
@app.get("/health")
def health():
    return {"status": "ok"}
20

Sujets avancés

Événements de lifespan

Le gestionnaire de contexte lifespan remplace les handlers dépréciés on_event('startup'/'shutdown'). Le code avant yield s'exécute au démarrage ; celui après yield à l'arrêt, même si le démarrage échoue. Servez-vous en pour initialiser les connexions DB, les modèles ML et les caches.

fastapi
from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # runs at startup
    print("starting up")
    app.state.cache = {}
    yield
    # runs at shutdown
    print("shutting down")
    await app.state.cache.clear()

app = FastAPI(lifespan=lifespan)

# the old @app.on_event("startup") / "shutdown" are deprecated
# in favor of the lifespan handler above.

Sous-applications (mount)

app.mount() attache une sous-application sous un préfixe de chemin, utile pour des API versionnées ou combiner plusieurs apps. Chaque sous-app a ses propres routes et schéma OpenAPI ; la doc du parent n'inclut pas les routes de l'enfant par défaut.

fastapi
from fastapi import FastAPI

app = FastAPI()

api_v1 = FastAPI()
api_v2 = FastAPI()

@api_v1.get("/items")
def v1_items():
    return {"version": 1}

@api_v2.get("/items")
def v2_items():
    return {"version": 2}

app.mount("/v1", api_v1)
app.mount("/v2", api_v2)

# GET /v1/items -> {"version": 1}
# GET /v2/items -> {"version": 2}

APIRouter

APIRouter regroupe des routes liées dans un module avec préfixe, tags, dépendances et réponses partagés. Incluez-le via app.include_router(router) (éventuellement avec son propre préfixe ou ses tags). C'est le pattern standard pour structurer des apps non triviales.

fastapi
from fastapi import APIRouter, Depends

router = APIRouter(
    prefix="/items",
    tags=["items"],
    dependencies=[Depends(verify_token)],
    responses={404: {"description": "Not found"}},
)

@router.get("/")
def list_items():
    return []

@router.get("/{item_id}")
def get_item(item_id: int):
    return {"id": item_id}

# in main.py: app.include_router(router)

Fichiers statiques

StaticFiles sert un répertoire de ressources statiques (images, CSS, JS) à un préfixe d'URL. Montez-le une fois par répertoire. Pour des frontends SPA, montez une route finale fourre-tout pointant vers index.html. Les fichiers statiques contournent le système de routage pour la rapidité.

fastapi
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

# serve files from ./static at /static
app.mount("/static", StaticFiles(directory="static"), name="static")

# /static/logo.png -> ./static/logo.png
# /static/css/app.css -> ./static/css/app.css

Réponse en flux

StreamingResponse envoie une réponse générée par tranches (un générateur/itérateur) au lieu de construire tout le corps en mémoire — idéal pour les exports CSV volumineux, le streaming de fichiers ou le SSE. Réglez media_type en conséquence pour que les clients gèrent le flux correctement.

fastapi
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv, io

app = FastAPI()

def iter_csv():
    output = io.StringIO()
    writer = csv.writer(output)
    writer.writerow(["id", "name"])
    for i in range(1000):
        writer.writerow([i, f"name-{i}"])
        yield output.getvalue()
        output.seek(0)
        output.truncate(0)

@app.get("/export.csv")
def export():
    return StreamingResponse(
        iter_csv(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=export.csv"},
    )

Classe de route personnalisée

Hériter d'APIRoute permet d'envelopper chaque handler de route avec une logique personnalisée (logging, tracing, timing) sans toucher à chaque endpoint. Réglez app.router.route_class ou passez route_class à APIRouter. Le handler s'exécute pour chaque requête correspondante.

fastapi
from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute
from typing import Callable

class LoggingRoute(APIRoute):
    def get_route_handler(self) -> Callable:
        original = super().get_route_handler()
        async def handler(request: Request) -> Response:
            print(f"-> {request.method} {request.url.path}")
            response = await original(request)
            print(f"<- {response.status_code}")
            return response
        return handler

app = FastAPI()
app.router.route_class = LoggingRoute

@app.get("/items")
def items():
    return {"items": []}

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.