Cum primești un corp de cerere JSON?

Question

Accepted Answer

Pentru a primi un corp de cerere JSON în FastAPI, declari un parametru de funcție tastat ca un **model Pydantic**. FastAPI citește corpul, analizează JSON-ul, îl validează împotriva modelului și ți trece un obiect tastat — automat.

## Modelul

```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 }
```

Declararea `item: Item` îi spune FastAPI să citească corpul cererii ca JSON, să îl analizeze într-un `Item`, și să **valideze** — funcția ta primește un obiect tastat, valid. Intrarea proastă este respinsă automat:

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

## Corp + cale + interogare împreună

```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 rutează parametrii inteligent: un substituent de cale → parametru de cale, un model Pydantic → corp de cerere, un parametru tastat simplu → parametru de interogare.

## Mai mulți parametri de corp / actualizări parțiale

```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
```

## De ce este important

Primirea și validarea corpurilor de cereri este esențială — aproape fiecare API care creează sau actualizează date are nevoie de asta, iar FastAPI o face remarcabil de curat: declararea unui parametru model Pydantic îți oferă analiza JSON automată, **validare** completă (cu erori clare la nivel de câmp 422), și un obiect tastat, eliminând analizarea manuală obositoare și predispusă la erori și validarea pe care alte framework-uri o necesită.

Validarea este, de asemenea, un beneficiu important al **securității/robusteții** — intrările prost formate sunt respinse înainte de a ajunge la logica ta.

Înțelegerea modului de a defini un model de corp, modul în care FastAPI distinge automat corpul de parametrii cale/interogare, și modele cum ar fi `exclude_unset` pentru actualizări parțiale este cunoaștere fundamentală zilnică pentru construirea oricărui punct final de scriere.