Kuinka polku- ja kyselyparametrit toimivat?

Question

Accepted Answer

FastAPI poimii **polkuparametrit** (osa URL-polusta) ja **kyselyparametrit** (symbolin `?` jälkeen) funktioargumenteista käyttäen tyyppivihjeita automaattiseen muuntamiseen ja validointiin.

## Polkuparametrit — osa URL:ia

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

Funktioluparaksi, jonka nimi vastaa `{placeholder}`ia polulla, tulee **polkuparametri**. Tyyppivihje (`int`) muuntaa automaattisesti merkkijonon URL:sta ja palauttaa selkeän 422-virheen, jos se ei vastaa.

## Kyselyparametrit — kaikki muu

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

Funktioluparametrit, jotka **eivät** ole polulla, tulevat **kyselyparametreiksi**. Oletuarvo tekee ne valinnaisiksi (`skip: int = 0`); `str | None = None` tekee nollarvoisen valinnaisenkyselyparametrin. Ilman oletusarvoa ne ovat pakollisia.

## Pakollinen vai valinnainen

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

## Molempien yhdistäminen

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

## Miksi se on tärkeää

Polku- ja kyselyparametrit ovat se, kuinka päätepisteet vastaanottavat syöttöä URL:sta — oleellinen lähes kaikille API-reiteille (resurssin noutaminen tunnuksella, suodattaminen, sivutus, haku).

FastAPI:n lähestymistapa on tyylikäs ja tärkeä syy sen tuottavuuteen: yksinkertaisesti ilmoittamalla tyypillytettyjä funktioparametreja saat automaattisen poimimisen, **tyypin muuntamisen**, **validoinnin** (selkeillä 422-virheillä virheellisestä syötöstä) ja pakollinen-vs-valinnainen-semantiikan (oletusarvojen kautta) — kaikki johdettu vakio-Python-tyyppivihjeistä ilman manuaalista jäsentämistä.

Eron ymmärtäminen (polkuparametrit tulevat `{placeholder}`ista, kaikki muu on kyselyparametri) ja kuinka oletusarvot hallitsevat valinnaisuutta on olennainen päivittäinen tieto FastAPI-päätepisteiden rakentamiseen.