Jak fungují parametry cesty a parametry dotazu?

Question

Accepted Answer

FastAPI extrahuje **parametry cesty** (součást cesty URL) a **parametry dotazu** (za `?`) z argumentů funkce, při čemž automaticky konvertuje a ověřuje pomocí nápověd typů.

## Parametry cesty — součást 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)
```

Parametr funkce, jehož název odpovídá `{placeholder}` v cestě, se stane **parametrem cesty**. Nápověda typu (`int`) automaticky konvertuje řetězec z URL a vrátí jasnou chybu 422, pokud se neshoduje.

## Parametry dotazu — všechno ostatní

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

Parametry funkce **ne**v cestě se stanou **parametry dotazu**. Výchozí hodnota je činí volitelné (`skip: int = 0`); `str | None = None` vytvoří volitelný nullable parametr dotazu. Bez výchozí hodnoty jsou povinné.

## Povinné vs volitelné

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

## Kombinování obou

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

## Proč to důležité

Parametry cesty a dotazu jsou způsob, jak koncové body přijímají vstup z URL — zásadní pro téměř každou trasu API (načítání zdroje podle id, filtrování, stránkování, vyhledávání).

Přístup FastAPI je elegantní a klíčový důvod jeho produktivity: jednoduše deklarovat typované parametry funkce vám dává automatickou extrakci, **konverzi typů**, **ověřování** (s jasnými chybami 422 při špatném vstupu) a sémantiku povinného vs. volitelného (přes výchozí hodnoty) — vše odvozené ze standardních nápověd typů Pythonu, bez ručního parsování.

Rozeznávání rozdílu (parametry cesty pocházejí z `{placeholders}`, všechno ostatní je parametr dotazu) a toho, jak výchozí hodnoty řídí volitelnost, je základní každodenní znalost pro vytváření koncových bodů FastAPI.