Path parameters y query parameters

Path parameters (/users/{user_id})

Los path parameters son variables que forman parte de la URL de tu endpoint. En lugar de crear una ruta fija como /users/123, puedes definir una ruta dinámica como /users/{user_id} donde user_id es una variable que puede tomar diferentes valores.

Esta funcionalidad te permite crear endpoints flexibles que pueden manejar múltiples recursos similares con una sola definición de ruta. Por ejemplo, en lugar de crear rutas separadas para cada usuario, puedes usar un path parameter para acceder a cualquier usuario mediante su identificador.

Sintaxis básica

Para definir un path parameter en FastAPI, utilizas llaves {} alrededor del nombre de la variable en la ruta:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(user_id):
    return {"user_id": user_id, "name": "Usuario ejemplo"}

En este ejemplo, user_id es el path parameter. Cuando alguien accede a /users/123, FastAPI automáticamente extrae el valor 123 y lo pasa como argumento a la función get_user().

Tipos de datos automáticos

FastAPI puede convertir automáticamente los path parameters a diferentes tipos de datos de Python. El tipo más común es int para identificadores numéricos:

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {
        "user_id": user_id,
        "name": f"Usuario número {user_id}",
        "type": type(user_id).__name__
    }

Con esta definición, si accedes a /users/123, FastAPI convierte automáticamente "123" (string) a 123 (integer). Si alguien intenta acceder a /users/abc, FastAPI devuelve un error de validación porque "abc" no se puede convertir a entero.

Múltiples path parameters

Puedes usar varios path parameters en la misma ruta. Cada uno debe estar definido tanto en la URL como en los parámetros de la función:

@app.get("/users/{user_id}/posts/{post_id}")
def get_user_post(user_id: int, post_id: int):
    return {
        "user_id": user_id,
        "post_id": post_id,
        "title": f"Post {post_id} del usuario {user_id}"
    }

Esta ruta responde a URLs como /users/5/posts/42, donde 5 se asigna a user_id y 42 a post_id.

Ejemplos prácticos

Aquí tienes algunos casos de uso comunes para path parameters:

Obtener información de un producto:

@app.get("/products/{product_id}")
def get_product(product_id: int):
    return {
        "id": product_id,
        "name": f"Producto {product_id}",
        "price": 29.99,
        "available": True
    }

Acceder a categorías:

@app.get("/categories/{category_name}")
def get_category(category_name: str):
    return {
        "category": category_name,
        "description": f"Productos de la categoría {category_name}",
        "total_products": 15
    }

Gestión de archivos:

@app.get("/files/{file_id}")
def get_file_info(file_id: str):
    return {
        "file_id": file_id,
        "filename": f"{file_id}.pdf",
        "size": "2.5 MB",
        "created": "2024-01-15"
    }

Orden de las rutas

Es importante considerar el orden en que defines tus rutas cuando combinas rutas fijas con path parameters:

# Correcto: ruta fija primero
@app.get("/users/me")
def get_current_user():
    return {"message": "Usuario actual"}

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

Si defines las rutas en orden inverso, /users/me sería interpretado como un path parameter donde user_id sería "me", lo que causaría un error al intentar convertirlo a entero.

Los path parameters son la base para crear APIs dinámicas que pueden manejar recursos individuales de manera eficiente, permitiendo que tu aplicación escale sin necesidad de definir rutas específicas para cada recurso.

Query parameters (?limit=10&skip=0)

Los query parameters son parámetros opcionales que se añaden al final de una URL después del símbolo ?. A diferencia de los path parameters que forman parte de la ruta, los query parameters proporcionan información adicional para filtrar, ordenar o configurar la respuesta del endpoint.

Estos parámetros son especialmente útiles cuando necesitas que los usuarios puedan personalizar los resultados sin cambiar la estructura básica de la URL. Por ejemplo, en lugar de crear múltiples endpoints para diferentes filtros, puedes usar un solo endpoint con query parameters.

Sintaxis básica

Para definir query parameters en FastAPI, simplemente añades parámetros adicionales a tu función que no estén definidos en la ruta:

from fastapi import FastAPI

app = FastAPI()

@app.get("/users")
def get_users(limit: int = 10):
    return {
        "users": [f"Usuario {i}" for i in range(1, limit + 1)],
        "total": limit
    }

En este ejemplo, limit es un query parameter. Puedes acceder al endpoint de estas formas:

• /users (usa el valor por defecto: 10)
• /users?limit=5 (usa el valor especificado: 5)

Múltiples query parameters

Puedes combinar varios query parameters en el mismo endpoint. Cada parámetro se separa con & en la URL:

@app.get("/products")
def get_products(limit: int = 10, skip: int = 0, category: str = "all"):
    products = [f"Producto {i}" for i in range(skip + 1, skip + limit + 1)]
    
    return {
        "products": products,
        "limit": limit,
        "skip": skip,
        "category": category,
        "total_shown": len(products)
    }

Este endpoint responde a URLs como:

• /products?limit=5&skip=10&category=electronics
• /products?limit=3 (skip=0 y category="all" por defecto)

Parámetros opcionales y requeridos

Los query parameters pueden ser opcionales (con valor por defecto) o requeridos:

# Parámetro opcional
@app.get("/search")
def search_items(query: str = ""):
    if not query:
        return {"message": "Introduce un término de búsqueda"}
    
    return {
        "query": query,
        "results": [f"Resultado para '{query}' #{i}" for i in range(1, 4)]
    }

# Parámetro requerido (sin valor por defecto)
@app.get("/filter")
def filter_items(status: str):
    return {
        "status": status,
        "items": [f"Item con status {status} #{i}" for i in range(1, 4)]
    }

Tipos de datos comunes

FastAPI convierte automáticamente los query parameters a los tipos de datos especificados:

@app.get("/analytics")
def get_analytics(
    active: bool = True,
    min_price: float = 0.0,
    max_results: int = 100,
    sort_by: str = "date"
):
    return {
        "filters": {
            "active": active,
            "min_price": min_price,
            "max_results": max_results,
            "sort_by": sort_by
        },
        "data": f"Resultados filtrados con los parámetros especificados"
    }

Ejemplos de uso:

• /analytics?active=false&min_price=25.50&max_results=50
• /analytics?active=true (otros valores por defecto)

Casos de uso prácticos

Paginación de resultados:

@app.get("/posts")
def get_posts(page: int = 1, per_page: int = 10):
    start = (page - 1) * per_page
    end = start + per_page
    
    return {
        "posts": [f"Post {i}" for i in range(start + 1, end + 1)],
        "page": page,
        "per_page": per_page,
        "total_pages": 10
    }

Filtrado de contenido:

@app.get("/articles")
def get_articles(published: bool = True, author: str = ""):
    articles = []
    
    if published:
        articles.extend([f"Artículo publicado {i}" for i in range(1, 4)])
    else:
        articles.extend([f"Borrador {i}" for i in range(1, 3)])
    
    if author:
        articles = [f"{article} por {author}" for article in articles]
    
    return {"articles": articles}

Configuración de respuesta:

@app.get("/data")
def get_data(format: str = "json", include_metadata: bool = False):
    data = {"values": [1, 2, 3, 4, 5]}
    
    if include_metadata:
        data["metadata"] = {
            "format": format,
            "generated_at": "2024-01-15T10:30:00",
            "version": "1.0"
        }
    
    return data

Combinando path y query parameters

Puedes usar ambos tipos de parámetros en el mismo endpoint:

@app.get("/users/{user_id}/posts")
def get_user_posts(user_id: int, published: bool = True, limit: int = 5):
    status = "publicados" if published else "borradores"
    
    return {
        "user_id": user_id,
        "posts": [f"Post {i} ({status})" for i in range(1, limit + 1)],
        "filter": "published" if published else "drafts"
    }

Este endpoint responde a URLs como /users/123/posts?published=false&limit=3, donde 123 es el path parameter y published y limit son query parameters.

Los query parameters te permiten crear endpoints flexibles que pueden adaptarse a diferentes necesidades sin multiplicar el número de rutas en tu API.