Jak działają parametry ścieżki i zapytania?

Question

Accepted Answer

FastAPI wyodrębnia **parametry ścieżki** (część ścieżki URL) i **parametry zapytania** (po `?`) z argumentów funkcji, używając type hints do automatycznej konwersji i walidacji.

## Parametry ścieżki — część adresu 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 funkcji, którego nazwa odpowiada `{placeholder}` w ścieżce, staje się **parametrem ścieżki**. Type hint (`int`) automatycznie konwertuje ciąg z adresu URL i zwraca wyraźny błąd 422, jeśli się nie zgadza.

## Parametry zapytania — wszystko inne

```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 funkcji **nie** znajdujące się w ścieżce stają się **parametrami zapytania**. Wartość domyślna czyni je opcjonalnymi (`skip: int = 0`); `str | None = None` tworzy opcjonalny parametr zapytania o wartości null. Bez wartości domyślnej są wymagane.

## Wymagane a opcjonalne

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

## Łączenie obu

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

## Dlaczego to ważne

Parametry ścieżki i zapytania są sposobem, w jaki punkty końcowe otrzymują dane wejściowe z adresu URL — podstawowe dla prawie każdej trasy API (pobieranie zasobu po identyfikatorze, filtrowanie, stronicowanie, wyszukiwanie).

Podejście FastAPI jest eleganckie i jest kluczowym powodem jego produktywności: proste zadeklarowanie parametrów funkcji o określonym typie daje automatyczną ekstrakcję, **konwersję typu**, **walidację** (z wyraźnymi błędami 422 na złych danych wejściowych) i semantykę wymaganego-vs-opcjonalnego (poprzez domyślne wartości) — wszystko wywnioskowane ze standardowych type hints Pythona, bez ręcznego parsowania.

Zrozumienie rozróżnienia (parametry ścieżki pochodzą z `{placeholders}`, wszystko inne to parametr zapytania) i sposobu kontrolowania opcjonalności przez wartości domyślne to niezbędna wiedza na co dzień do tworzenia punktów końcowych FastAPI.