Python Academy · Lección

Parámetros de ruta, parámetros de consulta y cuerpos de solicitud

Defina parámetros tipados y esquemas de cuerpos de solicitud con Pydantic.

Parámetros de ruta, parámetros de consulta y cuerpos de solicitud es una lección gratuita de Python Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Python Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Python Academy incluye 4 lecciones en total.

Validación de parámetros de ruta

Añada validadores a los parámetros de ruta mediante Path(): establezca las restricciones ge, le, gt y lt.

from fastapi import FastAPI, Path
app = FastAPI()

@app.get("/items/{item_id}")
def get_item(item_id: int = Path(ge=1, le=1000)):
    return {"item_id": item_id}

# GET /items/0  → 422 (must be >= 1)

Validación de parámetros de consulta

Use Query() para añadir validación, valores predeterminados, alias y descripciones a los parámetros de consulta.

from fastapi import FastAPI, Query
app = FastAPI()

@app.get("/search")
def search(
    q: str = Query(min_length=2, max_length=50),
    page: int = Query(default=1, ge=1),
):
    return {"q": q, "page": page}

Parámetros de consulta opcionales

Use | None = None (Python 3.10+) u Optional[str] = None para hacer opcional un parámetro de consulta.

from fastapi import FastAPI
app = FastAPI()

@app.get("/users")
def list_users(
    dept: str | None = None,
    active: bool = True
):
    return {"dept": dept, "active": active}

# GET /users → dept=None, active=True
# GET /users?dept=HR&active=false

Varios valores para un parámetro de consulta

Acepte una lista de valores para un único parámetro de consulta con list[str] y Query().

from fastapi import FastAPI, Query
from typing import Annotated
app = FastAPI()

@app.get("/filter")
def filter_items(tags: Annotated[list[str], Query()] = []):
    return {"tags": tags}

# GET /filter?tags=python&tags=web

Cuerpos de solicitud anidados

Los modelos de Pydantic pueden anidarse. FastAPI gestiona automáticamente el JSON anidado.

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()

class Address(BaseModel):
    street: str
    city: str

class User(BaseModel):
    name: str
    address: Address

@app.post("/users")
def create_user(user: User):
    return user.model_dump()

Restricciones de campos en Pydantic

Use Field() dentro de un modelo para añadir restricciones, valores predeterminados y descripciones a campos individuales.

from pydantic import BaseModel, Field

class Product(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)
    quantity: int = Field(ge=0, default=0, description="Items in stock")

Cuerpo de solicitud, ruta y consulta juntos

Combine los tres tipos de parámetros en un mismo endpoint. FastAPI los distingue por su ubicación: la ruta aparece en la URL, los tipos simples son parámetros de consulta y los modelos forman parte del cuerpo.

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()

class ItemUpdate(BaseModel):
    name: str
    price: float

@app.put("/shops/{shop_id}/items/{item_id}")
def update_item(
    shop_id: int,
    item_id: int,
    item: ItemUpdate,
    notify: bool = False,
):
    return {"shop": shop_id, "item": item_id,
            "data": item.model_dump(), "notify": notify}

Carga de archivos

Use UploadFile y File() para aceptar cargas de archivos. Acceda al contenido con await file.read().

from fastapi import FastAPI, UploadFile, File
app = FastAPI()

@app.post("/upload")
async def upload(file: UploadFile = File(...)):
    content = await file.read()
    return {"filename": file.filename, "size": len(content)}

Datos de formulario

Use Form() para aceptar datos de formularios HTML (application/x-www-form-urlencoded o multipart/form-data).

# pip install python-multipart
from fastapi import FastAPI, Form
app = FastAPI()

@app.post("/login")
def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

Resumen de la validación de solicitudes

FastAPI valida automáticamente todos los tipos de parámetros. Las entradas no válidas devuelven HTTP 422 con un mensaje detallado antes de llamar a su controlador.

# Auto-validated:
# - Path params: type coercion, Path() constraints
# - Query params: Query() constraints, type coercion
# - Request body: Pydantic model validation
# - All errors → HTTP 422 Unprocessable Entity
# - No manual validation needed

Alias y desuso

Use alias= en Query() o Field() para aceptar un nombre diferente en la solicitud, y deprecated=True para marcar parámetros antiguos.

from fastapi import FastAPI, Query
app = FastAPI()

@app.get("/items")
def get_items(
    q: str | None = Query(default=None, alias="search-query"),
    old: str | None = Query(default=None, deprecated=True),
):
    return {"q": q, "old": old}

# GET /items?search-query=python

Comprobación rápida

¿Cómo distingue FastAPI entre un parámetro de ruta, un parámetro de consulta y un cuerpo de solicitud?

Resumen

Use Path()/Query() para definir restricciones de parámetros. Anide modelos de Pydantic para cuerpos complejos. Combine libremente parámetros de ruta, consulta y cuerpo. UploadFile gestiona archivos y Form() gestiona formularios HTML. FastAPI valida todo antes de ejecutar su controlador.

Preguntas frecuentes

¿La lección «Parámetros de ruta, parámetros de consulta y cuerpos de solicitud» es gratis?

Sí — el texto completo de «Parámetros de ruta, parámetros de consulta y cuerpos de solicitud» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Python Academy, actualiza a CoddyKit PRO. El curso de Python Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Parámetros de ruta, parámetros de consulta y cuerpos de solicitud»?

Defina parámetros tipados y esquemas de cuerpos de solicitud con Pydantic. Practicas Python Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Python Academy?

No se requiere experiencia previa. Python Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Parámetros de ruta, parámetros de consulta y cuerpos de solicitud»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Python Academy?

Sí. Cada lección de Python Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Configuración de un proyecto FastAPI y primer endpoint
Parámetros de ruta, parámetros de consulta y cuerpos de solicitud
Inyección de dependencias y autenticación
Endpoints asíncronos e integración con bases de datos

← Volver a Python Academy