Come si riceve un corpo di richiesta JSON?

Question

Accepted Answer

Per ricevere un corpo di richiesta JSON in FastAPI, si dichiara un parametro di funzione tipizzato come **modello Pydantic**. FastAPI legge il corpo, analizza il JSON, lo valida rispetto al modello e ti passa un oggetto tipizzato — automaticamente.

## Perché è importante

```python
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None      # optional field

@app.post("/items")
def create_item(item: Item):             # `item: Item` → read & validate the JSON body
    # `item` is a fully-validated Item object here
    return {"name": item.name, "total": item.price * 1.1}
```

```json
// request body the client sends:
{ "name": "Phone", "price": 999.0 }
```

Dichiarare `item: Item` dice a FastAPI di leggere il corpo della richiesta come JSON, analizzarlo in un `Item` e **convalidarlo** — la tua funzione riceve un oggetto tipizzato e valido. L'input errato viene rifiutato automaticamente:

```json
// POST { "name": "Phone" }  (missing price) → automatic 422:
{ "detail": [{ "loc": ["body", "price"], "msg": "field required" }] }
```

## Body + path + query insieme

```python
@app.put("/items/{item_id}")
def update(item_id: int, item: Item, notify: bool = False):
    # item_id = path param, item = JSON body (Pydantic model), notify = query param
    # FastAPI distinguishes them by type/location automatically
```

FastAPI instrada intelligentemente i parametri: un placeholder di percorso → parametro di percorso, un modello Pydantic → corpo della richiesta, un parametro semplicemente tipizzato → parametro di query.

## Più parametri body / aggiornamenti parziali

```python
@app.patch("/items/{id}")
def patch(id: int, item: ItemUpdate):       # use a model with all-optional fields for PATCH
    update_data = item.model_dump(exclude_unset=True)   # only fields the client sent
```

## Perché è importante

Ricevere e convalidare i corpi delle richieste è essenziale — quasi tutte le API che creano o aggiornano dati ne hanno bisogno, e FastAPI lo rende straordinariamente pulito: dichiarare un parametro modello Pydantic ti dà l'analisi JSON automatica, la completa **convalida** (con errori 422 a livello di campo chiari) e un oggetto tipizzato, eliminando l'analisi manuale tediosae soggetta a errori e la convalida che altri framework richiedono.

La convalida è anche un beneficio chiave di **sicurezza/robustezza** — l'input malformato viene rifiutato prima di raggiungere la tua logica.

Capire come definire un modello body, come FastAPI distingue automaticamente il body dai parametri path/query, e pattern come `exclude_unset` per gli aggiornamenti parziali è una conoscenza fondamentale e quotidiana per costruire qualsiasi endpoint di scrittura.