Comment définir les codes de statut et les en-têtes ?

Question

Accepted Answer

FastAPI retourne `200 OK` par défaut, mais vous contrôlez le **code de statut** (via le décorateur ou l'objet response) et les **en-têtes** quand vous avez besoin d'un comportement différent — important pour la sémantique REST appropriée.

## Définir un code de statut par défaut sur la route

```python
from fastapi import status

@app.post("/items", status_code=status.HTTP_201_CREATED)   # 201 for resource creation
def create_item(item: Item):
    return item                                             # returns with 201

@app.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)  # 204
def delete_item(id: int):
    ...
```

Le paramètre `status_code` du décorateur définit le statut de succès par défaut. Utiliser les constantes `status` (par ex. `status.HTTP_201_CREATED`) est plus clair que les nombres magiques. Les codes corrects sont importants : `201` pour créé, `204` pour pas de contenu, etc.

## Codes de statut et en-têtes dynamiques via l'objet Response

```python
from fastapi import Response

@app.get("/items/{id}")
def get_item(id: int, response: Response):
    item = db.get(id)
    if not item:
        response.status_code = status.HTTP_404_NOT_FOUND   # set dynamically
        return {"error": "not found"}
    response.headers["X-Custom"] = "value"                  # set a custom header
    return item
```

Injecter un paramètre `Response` vous permet de définir le code de statut et les en-têtes **conditionnellement** au moment de l'exécution.

## Erreurs : lever HTTPException

```python
from fastapi import HTTPException

@app.get("/items/{id}")
def get_item(id: int):
    item = db.get(id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found",
                            headers={"X-Error": "NotFound"})   # status + detail + headers
    return item
```

Pour les réponses d'erreur, `raise HTTPException(...)` est la façon idiomatique — elle définit le statut, un message JSON `detail`, et des en-têtes optionnels.

## Retourner une Response personnalisée directement

```python
from fastapi.responses import JSONResponse
return JSONResponse(content={...}, status_code=202, headers={"X-Custom": "v"})
```

## Pourquoi c'est important

Les codes de statut et en-têtes appropriés sont essentiels pour construire des API REST correctes et bien comportées — les clients et les outils s'appuient sur la sémantique HTTP standard (201 pour créé, 404 pour non trouvé, 204 pour pas de contenu, etc.), donc retourner le bon code fait partie d'un contrat d'API de qualité.

FastAPI vous donne un contrôle propre : un `status_code` par défaut sur la route pour le cas courant, l'objet `Response` injectable pour les codes/en-têtes dynamiques, et `HTTPException` comme la façon idiomatique de signaler les erreurs avec le statut approprié et un détail JSON.

Comprendre ces mécanismes — et utiliser les constantes `status` pour la clarté — est une connaissance quotidienne pour construire des API qui se comportent correctement et communiquent clairement avec leurs consommateurs.