Comment fonctionnent les paramètres de chemin et les paramètres de requête ?

Question

Accepted Answer

FastAPI extrait les **paramètres de chemin** (partie du chemin d'URL) et les **paramètres de requête** (après `?`) à partir des arguments de fonction, en utilisant les indices de type pour les convertir et les valider automatiquement.

## Paramètres de chemin — partie de l'URL

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

Un paramètre de fonction dont le nom correspond à un `{placeholder}` dans le chemin devient un **paramètre de chemin**. L'indice de type (`int`) convertit automatiquement la chaîne de l'URL et retourne une erreur 422 claire si elle ne correspond pas.

## Paramètres de requête — tout le reste

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

Les paramètres de fonction **non** présents dans le chemin deviennent des **paramètres de requête**. Une valeur par défaut les rend optionnels (`skip: int = 0`) ; `str | None = None` crée un paramètre de requête optionnel nullable. Sans valeur par défaut, ils sont obligatoires.

## Requis vs optionnel

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## Combinaison des deux

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## Pourquoi c'est important

Les paramètres de chemin et de requête sont la façon dont les points de terminaison reçoivent une entrée à partir de l'URL — fondamental pour presque chaque route d'API (récupérer une ressource par id, filtrer, paginer, rechercher).

L'approche de FastAPI est élégante et une raison clé pour laquelle il est productif : déclarer simplement des paramètres de fonction typés vous donne l'extraction automatique, la **conversion de type**, la **validation** (avec des erreurs 422 claires pour les entrées invalides) et la sémantique requis-vs-optionnel (via les valeurs par défaut) — tout dérivé des indices de type Python standard, sans analyse manuelle.

Comprendre la distinction (les paramètres de chemin proviennent de `{placeholders}`, tout le reste est un paramètre de requête) et comment les valeurs par défaut contrôlent l'optionnalité est une connaissance essentielle au quotidien pour construire des points de terminaison FastAPI.