Hoe ontvang je een JSON-aanvraaghoofdtekst?

Question

Accepted Answer

Om een JSON-aanvraaghoofdtekst in FastAPI te ontvangen, declareer je een functionparameter getypeerd als een **Pydantic-model**. FastAPI leest de hoofdtekst, parseert de JSON, valideert deze tegen het model en geeft je een getypeerd object — automatisch.

## Het patroon

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

Door `item: Item` te declareren vertellen je FastAPI dat het de aanvraaghoofdtekst als JSON moet lezen, deze in een `Item` moet parseren, en **valideren** — je functie ontvangt een getypeerd, geldig object. Slechte invoer wordt automatisch afgewezen:

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

## Hoofdtekst + pad + query samen

```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 routeert parameters intelligent: een paadplakeholder → padparameter, een Pydantic-model → aanvraaghoofdtekst, een eenvoudig getypeerde parameter → queryparameter.

## Meerdere hoofdtekstparameters / gedeeltelijke updates

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

## Waarom het belangrijk is

Aanvraaghoofdteksten ontvangen en valideren is essentieel — bijna elke API die gegevens maakt of bijwerkt, heeft dit nodig, en FastAPI maakt het opmerkelijk schoon: het declareren van een Pydantic-modelparameter geeft je automatisch JSON-parsing, volledige **validatie** (met duidelijke fouten op veldniveau 422), en een getypeerd object, wat de vervelende, foutgevoelige handmatige parsing en validatie die andere frameworks vereisen, elimineert.

De validatie is ook een belangrijk **veiligheids-/robuustheid**-voordeel — verkeerd gevormde invoer wordt geweigerd voordat het je logica bereikt.

Begrijpen hoe je een hoofdtekstmodel definieert, hoe FastAPI hoofdtekst van pad-/queryparameters automatisch onderscheidt, en patronen zoals `exclude_unset` voor gedeeltelijke updates zijn fundamentele dagelijkse kennis voor het bouwen van elk schrijfendpoint.