Comment définir les routes (path operations) ?

Question

Accepted Answer

Dans FastAPI, une **path operation** est une route — une fonction décorée avec un décorateur de méthode HTTP (`@app.get`, `@app.post`, etc.) qui traite les demandes vers un chemin. La valeur de retour de la fonction est automatiquement sérialisée en JSON.

## Définir les routes pour chaque méthode HTTP

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → automatically JSON-serialized

@app.get("/items/{item_id}")      # GET /items/5 — path parameter
def get_item(item_id: int):        # type hint converts "5" → int (and validates)
    return {"id": item_id}

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

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE work the same way
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

Chaque décorateur mappe une méthode HTTP + un chemin à un gestionnaire. Le nom de la fonction vous appartient ; le décorateur définit la route. Les dicts/listes/modèles Pydantic retournés sont sérialisés en JSON automatiquement — pas de `json.dumps` manuel.

## L'ordre importe pour les chemins qui se chevauchent

```python
@app.get("/users/me")            # ✅ specific route FIRST
def read_me(): ...
@app.get("/users/{user_id}")     # dynamic AFTER — else "me" matches {user_id}
def read_user(user_id: int): ...
```

FastAPI fait correspondre les routes dans l'ordre de déclaration, donc mettez les chemins statiques avant les dynamiques.

## Métadonnées de l'opération (alimentent les docs)

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

Les paramètres du décorateur (`tags`, `summary`, `status_code`, `response_model`) configurent le comportement et enrichissent la documentation générée automatiquement.

## Pourquoi c'est important

Les path operations sont la fondation de chaque application FastAPI — elles définissent les endpoints de votre API et comment les demandes sont traitées.

Comprendre le modèle décorateur-par-méthode-HTTP, que les valeurs de retour sont automatiquement sérialisées en JSON (sans boilerplate), que les type hints sur les paramètres pilotent la conversion et la validation, et que l'ordre des routes importe pour les chemins qui se chevauchent est une connaissance essentielle au quotidien pour construire n'importe quel endpoint.

Les métadonnées du décorateur alimentent aussi la documentation automatique de FastAPI, reliant les routes directement aux docs.

C'est la première et la plus fondamentale chose à maîtriser dans FastAPI.