Kif tqabbel ġisem tal-istqarr JSON?

Question

Accepted Answer

Biex tqabbel ġisem tal-istqarr JSON f'FastAPI, tiddikjara parametru tal-funzjoni tipizzat bħala **mudell Pydantic**. FastAPI jaqra l-ġisem, jipparsa l-JSON, jivvalidaw kontra l-mudell, u jgħaddilek oġġett tipizzat — awtomatikament.

## Għaliex huwa importanti

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

Dikjarazzjoni ta' `item: Item` tgħid lil FastAPI biex taqra l-ġisem tal-istqarr bħala JSON, tiparsaha f' `Item`, u **tivvalidaw** — il-funzjoni tiegħek taqbel oġġett tipizzat u validu. L-input ħażin jiġu rifutati awtomatikament:

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

## Ġisem + mogħdija + mistoqsija flimkien

```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 b'mod intelliġenti jirrimwalcja parametri: placeholder tal-mogħdija → parametru tal-mogħdija, mudell Pydantic → ġisem tal-istqarr, parametru sempliċi-tipizzat → parametru tal-mistoqsija.

## Multipli parametri tal-ġisem / aġornamenti parzjali

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

## Għaliex huwa importanti

Il-qbil u l-validazzjoni tal-ġisem tal-istqarr huwa essenzjali — kważi kull API li joħloq jew aġorna data għandu bżonn tiegħu, u FastAPI jagħmelhiex straordinarjament nadif: dikjarazzjoni ta' parametru tal-mudell Pydantic tagħtik parsing JSON awtomatiku, **validazzjoni** kompleta (b'żbalji ta' livell ta' qasam 422 ċari), u oġġett tipizzat, u telimina l-parsing manwali tedwiesu u propenzi għal żbalji u validazzjoni li frameworks oħra jeħtieġu.

Il-validazzjoni hija wkoll benefiċju essenzjali ta' **sigurtà/sħiħ** — input mitwaqqaf mhux tajjep jiġu rifutati qabel ma jilħqu l-loġika tiegħek.

L-intelliġenza ta' kif tiddiffinixxi mudell ta' ġisem, kif FastAPI awtomatikament jiddistinwixxi l-ġisem minn parametri tal-mogħdija/mistoqsija, u mudelli bħal `exclude_unset` għal aġornamenti parzjali hija għarifa fundamentali ta' kuljum għall-bini ta' punt tat-tmiem tal-kitba.