Kif jaħdmu l-parametri tal-passaġġ u l-parametri tal-mistoqsija?

Question

Accepted Answer

FastAPI jestraħ **parametri tal-passaġġ** (parti tal-passaġġ URL) u **parametri tal-mistoqsija** (wara `?`) minn argumenti tal-funzjoni, billi juża għarfiet tat-tip għal konverżjoni u validazzjoni awtomatika.

## Parametri tal-passaġġ — parti tal-URL

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

Parametru tal-funzjoni li ismu jaqbel ma `{placeholder}` fil-passaġġ isir **parametru tal-passaġġ**. L-għarfija tat-tip (`int`) taqleb awtomatikament il-string mill-URL u tirritorna żball 422 ċar jekk ma jaqbilx.

## Parametri tal-mistoqsija — kollox ieħor

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

Parametri tal-funzjoni **mhux** fil-passaġġ isiru **parametri tal-mistoqsija**. Valur default jagħmluhom fakultattivi (`skip: int = 0`); `str | None = None` jagħmel parametru tal-mistoqsija fakultattiv null. Mingħajr default, huma meħtieġa.

## Meħtieġ vs fakultattiv

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## Jikkombinaw it-tnejn

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## Għaliex dan importanti

L-parametri tal-passaġġ u tal-mistoqsija huma kif l-endpoints jirċievu input mill-URL — fundamentali għal bejn wieħed u ieħor kull rotta API (jeħel risorsa bi id, filtrazzjoni, paġinazzjoni, tfittxija).

L-approċċ tal-FastAPI huwa eleganti u raġuni ewlenija għat-tieni li hu produttiv: sempliċement billi tiddikjara parametri tal-funzjoni ttipati tagħtik estrazzjoni awtomatika, **konverżjoni tat-tip**, **validazzjoni** (bi żbalali 422 ċari fuq input ħażin) u semantika meħtieġ-versus-fakultattiv (permezz ta' defaults) — kollox derivat minn għarfiet tat-tip Python standard, mingħajr parsing manuali.

Il-fehim tad-distinzjoni (l-parametri tal-passaġġ ḥin `{placeholders}`, kollox ieħor huwa parametru tal-mistoqsija) u kif id-defaults jikkontrolla l-fakultattività huma għarifa essenzjali ta' kuljum għall-bini tal-endpoints FastAPI.