Cum funcționează parametrii de cale și interogare?

Question

Accepted Answer

FastAPI extrage **parametrii de cale** (parte a caii URL) și **parametrii de interogare** (după `?`) din argumentele funcției, folosind type hints pentru a le converti și valida automat.

## Parametrii de cale — parte a URL-ului

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

Un parametru de funcție al cărui nume se potrivește cu un `{placeholder}` în cale devine un **parametru de cale**. Type hint-ul (`int`) convertește automat șirul din URL și returnează o eroare clară 422 dacă nu se potrivește.

## Parametrii de interogare — totul altceva

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

Parametrii de funcție **nu** în cale devin **parametrii de interogare**. O valoare implicită îi face opționali (`skip: int = 0`); `str | None = None` creează un parametru de interogare opțional care acceptă null. Fără o valoare implicită, sunt obligatori.

## Obligatoriu vs opțional

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

## Combinând ambele

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

## De ce conteaza

Parametrii de cale și interogare sunt modul în care punctele finale primesc intrări din URL — esențial pentru aproape fiecare rută API (preluarea unei resurse după id, filtrare, paginare, căutare).

Abordarea FastAPI este elegantă și un motiv cheie pentru productivitatea sa: pur și simplu declarând parametri de funcție tipați vă oferă extragere automată, **conversie de tip**, **validare** (cu erori clare 422 la intrări greșite) și semantică obligatorie-vs-opțională (prin valori implicite) — totul derivat din type hints Python standard, fără parsing manual.

Înțelegerea distincției (parametrii de cale provin din `{placeholders}`, totul altceva este un parametru de interogare) și modul în care valorile implicite controlează opcionalitatea este cunoștințe esențiale de zi cu zi pentru construirea punctelor finale FastAPI.