Come imposti i codici di stato e gli header?

Question

Accepted Answer

FastAPI restituisce `200 OK` per impostazione predefinita, ma puoi controllare il **codice di stato** (tramite il decoratore o l'oggetto response) e gli **header** quando hai bisogno di un comportamento diverso — importante per la corretta semantica REST.

## Impostazione di un codice di stato predefinito sulla rotta

```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):
    ...
```

Il parametro del decoratore `status_code` imposta lo stato di successo predefinito. Usare le costanti `status` (ad es. `status.HTTP_201_CREATED`) è più chiaro dei numeri magici. I codici corretti sono importanti: `201` per creato, `204` per nessun contenuto, ecc.

## Codici di stato e header dinamici tramite l'oggetto 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
```

L'iniezione di un parametro `Response` ti permette di impostare il codice di stato e gli header **condizionatamente** a runtime.

## Errori: raise 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
```

Per le risposte di errore, `raise HTTPException(...)` è il modo idiomatico — imposta lo stato, un messaggio JSON `detail` e header opzionali.

## Restituzione di una Response personalizzata direttamente

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

## Perché è importante

I codici di stato e gli header appropriati sono essenziali per costruire API REST corrette e ben funzionanti — i client e gli strumenti si affidano alla semantica HTTP standard (201 per creato, 404 per non trovato, 204 per nessun contenuto, ecc.), quindi restituire il codice giusto fa parte del contratto di qualità di un'API.

FastAPI ti dà un controllo pulito: un `status_code` predefinito sulla rotta per il caso comune, l'oggetto `Response` iniettabile per codici/header dinamici, e `HTTPException` come il modo idiomatico per segnalare errori con lo stato appropriato e un detail JSON.

Comprendere questi meccanismi — e usare le costanti `status` per chiarezza — è una conoscenza quotidiana per costruire API che si comportano correttamente e comunicano chiaramente con i loro consumatori.