¿Cómo funcionan los parámetros de ruta y de consulta?

Question

Accepted Answer

FastAPI extrae **parámetros de ruta** (parte de la ruta URL) y **parámetros de consulta** (después de `?`) de los argumentos de la función, utilizando type hints para convertir y validar automáticamente.

## Parámetros de ruta — parte de la 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 parámetro de función cuyo nombre coincide con un `{placeholder}` en la ruta se convierte en un **parámetro de ruta**. El type hint (`int`) convierte automáticamente la cadena de la URL y devuelve un error 422 claro si no coincide.

## Parámetros de consulta — todo lo demás

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

Los parámetros de función **no** en la ruta se convierten en **parámetros de consulta**. Un valor por defecto los hace opcionales (`skip: int = 0`); `str | None = None` hace un parámetro de consulta opcional que acepta nulos. Sin valor por defecto, son obligatorios.

## Obligatorio 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 qué es importante

Los parámetros de ruta y de consulta son la forma en que los puntos finales reciben entrada de la URL — fundamentales para casi todas las rutas API (obtener un recurso por id, filtrado, paginación, búsqueda).

El enfoque de FastAPI es elegante y una razón clave de su productividad: simplemente declarar parámetros de función tipados te da extracción automática, **conversión de tipos**, **validación** (con errores 422 claros en entrada incorrecta) y semántica obligatoria vs. opcional (mediante valores por defecto) — todo derivado de type hints estándar de Python, sin parseo manual.

Comprender la distinción (los parámetros de ruta provienen de `{placeholders}`, todo lo demás es un parámetro de consulta) y cómo los valores por defecto controlan la opcionalidad es conocimiento esencial cotidiano para construir puntos finales de FastAPI.