Come funzionano i parametri di percorso e i parametri di query?

Question

Accepted Answer

FastAPI estrae i **parametri di percorso** (parte del percorso URL) e i **parametri di query** (dopo `?`) dagli argomenti della funzione, utilizzando i suggerimenti di tipo per convertire e convalidare automaticamente.

## Parametri di percorso — parte dell'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)
```

Un parametro di funzione il cui nome corrisponde a un `{placeholder}` nel percorso diventa un **parametro di percorso**. Il suggerimento di tipo (`int`) converte automaticamente la stringa dall'URL e restituisce un errore 422 chiaro se non corrisponde.

## Parametri di query — tutto il resto

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

I parametri di funzione **non** nel percorso diventano **parametri di query**. Un valore predefinito li rende opzionali (`skip: int = 0`); `str | None = None` crea un parametro di query opzionale nullable. Senza un valore predefinito, sono obbligatori.

## Obbligatori vs opzionali

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

## Combinare entrambi

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

## Perché è importante

I parametri di percorso e di query sono il modo in cui gli endpoint ricevono input dall'URL — fondamentale per quasi ogni route API (recuperare una risorsa per id, filtrare, paginare, cercare).

L'approccio di FastAPI è elegante ed è una ragione chiave della sua produttività: semplicemente dichiarando parametri di funzione tipizzati si ottiene l'estrazione automatica, la **conversione di tipo**, la **convalida** (con errori 422 chiari su input non validi) e la semantica obbligatoria-vs-opzionale (tramite valori predefiniti) — tutto derivato dai suggerimenti di tipo Python standard, senza analisi manuale.

Comprendere la distinzione (i parametri di percorso provengono da `{placeholders}`, tutto il resto è un parametro di query) e come i valori predefiniti controllano l'opzionalità è una conoscenza essenziale quotidiana per costruire endpoint FastAPI.