Kako delujejo parametri poti in parametri poizvedbe?

Question

Accepted Answer

FastAPI ekstrahira **parametre poti** (del URL poti) in **parametre poizvedbe** (za `?`) iz argumentov funkcije, pri čemer uporablja namige tipov za samodejno pretvarjanje in preverjanje.

## Parametri poti — del URL-ja

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

Parameter funkcije, katerega ime se ujema s `{placeholder}` v poti, postane **parameter poti**. Namig tipa (`int`) samodejno pretvori niz iz URL-ja in vrne jasno napako 422, če se ne ujema.

## Parametri poizvedbe — vse ostalo

```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 funkcije, ki **niso** v poti, postanejo **parametri poizvedbe**. Privzeta vrednost jih naredi izbirne (`skip: int = 0`); `str | None = None` naredi izbiran parameter poizvedbe z ničelno vrednostjo. Brez privzete vrednosti so obvezni.

## Obvezni proti izbirnim

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

## Kombiniranje obojega

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

## Zakaj je to važno

Parametri poti in poizvedbe so način, na katerega končne točke prejemajo vhod iz URL-ja — temeljni za skoraj vsako smer API-ja (pridobivanje vira po ID-ju, filtriranje, razdeljevanje na strani, iskanje).

Pristop FastAPI je eleganten in ključen razlog, da je produktiven: enostavna deklaracija tipiziranih parametrov funkcije vam omogoči samodejno ekstrakcijo, **pretvarjanje tipov**, **preverjanje** (s jasnimi napakami 422 pri slabem vnosu) in semantiko obvezno-proti-izbirno (prek privzetih vrednosti) — vse izpeljano iz standardnih namigov tipov Python, brez ročnega razčlenjevanja.

Razumevanje razlike (parametri poti prihajajo iz `{placeholder}`, vse ostalo je parameter poizvedbe) in kako privzete vrednosti nadzorujejo izbirnost, je bistveno vsakodnevno znanje za gradnjo končnih točk FastAPI.