Kako funkcioniraju parametri puta i parametri upita?

Question

Accepted Answer

FastAPI ekstraktuje **parametre puta** (dio URL puta) i **parametre upita** (nakon `?`) iz argumenata funkcije, koristeći type hints za automatsku konverziju i validaciju.

## Parametri puta — dio URL-a

```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 čije ime odgovara `{placeholder}` u putu postaje **parametar puta**. Tip hint (`int`) automatski konvertuje string iz URL-a i vraća jasnu 422 grešku ako ne odgovara.

## Parametri upita — sve 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 koji **nisu** u putu postaju **parametri upita**. Zadana vrijednost čini ih opcionalnima (`skip: int = 0`) ; `str | None = None` čini opcioni parametar upita koji može biti null. Bez zadane vrijednosti, obavezni su.

## Obavezni ili opcioni

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

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

## Zašto je to važno

Parametri puta i upita su način na koji krajnje točke primaju ulaz iz URL-a — fundamentalno za gotovo svaki API rut (preuzimanje resursa po id, filtriranje, paginacija, pretraživanje).

Pristup FastAPI-ja je elegantan i ključan razlog zašto je produktivan: jednostavnom deklaracijom typiziranih parametara funkcije dobivate automatsku ekstrakciju, **konverziju tipova**, **validaciju** (s jasnim 422 greškama na lošem ulazu) i semantiku obaveznoga-naspram-opcionalnoga (preko zadanih vrijednosti) — sve izvedeno iz standardnih Python type hints, bez ručne analize.

Razumijevanje razlike (parametri puta dolaze iz `{placeholders}`, sve ostalo je parametar upita) i kako zadane vrijednosti kontroliraju opcionalnost je esencijalno svakodnevno znanje za izgradnju FastAPI krajnjih točaka.