Como funcionam parâmetros de caminho e consulta?

Question

Accepted Answer

FastAPI extrai **parâmetros de caminho** (parte do caminho da URL) e **parâmetros de consulta** (após `?`) dos argumentos da função, usando type hints para convertê-los e validá-los automaticamente.

## Parâmetros de caminho — parte da 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)
```

Um parâmetro de função cujo nome corresponde a um `{placeholder}` no caminho torna-se um **parâmetro de caminho**. O type hint (`int`) converte automaticamente a string da URL e retorna um erro claro 422 se não corresponder.

## Parâmetros de consulta — todo o 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}
```

Parâmetros de função **não** no caminho tornam-se **parâmetros de consulta**. Um valor padrão os torna opcionais (`skip: int = 0`); `str | None = None` cria um parâmetro de consulta opcional anulável. Sem um valor padrão, eles são obrigatórios.

## Obrigatório vs opcional

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

## Combinando ambos

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

## Por que isso importa

Parâmetros de caminho e consulta são como os endpoints recebem entrada da URL — fundamentais para quase toda rota de API (buscar um recurso por id, filtrar, paginar, pesquisar).

A abordagem do FastAPI é elegante e uma razão-chave para sua produtividade: simplesmente declarar parâmetros de função tipados lhe dá extração automática, **conversão de tipo**, **validação** (com erros claros 422 em entrada inválida) e semântica obrigatória-vs-opcional (via valores padrão) — tudo derivado de type hints Python padrão, sem parsing manual.

Entender a distinção (parâmetros de caminho vêm de `{placeholders}`, tudo o mais é um parâmetro de consulta) e como os valores padrão controlam a opcionalidade é conhecimento essencial do dia a dia para construir endpoints do FastAPI.