Rutas, parámetros y cuerpo

Teoría22 min20 XP

Una API útil responde según lo que le piden: el gasto número 5, los de categoría "comida", o crea uno con los datos que envías. FastAPI lee la parte variable de la URL (PARÁMETROS DE RUTA), los filtros (PARÁMETROS DE CONSULTA) y los datos enviados (el CUERPO) —y los valida por ti usando type hints—. Hoy haces tu API dinámica: que responda a peticiones concretas.

Las partes de un pedido

Parámetros de ruta y de consulta

parametros.py

from fastapi import FastAPI

app = FastAPI()

GASTOS = [
  {"id": 1, "nombre": "Café", "valor": 4000, "categoria": "comida"},
  {"id": 2, "nombre": "Bus", "valor": 2800, "categoria": "transporte"},
  {"id": 3, "nombre": "Cine", "valor": 18000, "categoria": "ocio"},
]

# PARÁMETRO DE RUTA: la parte variable de la URL, tipada.
# GET /gastos/2  ->  gasto_id = 2 (FastAPI valida que sea int)
@app.get("/gastos/{gasto_id}")
def obtener_gasto(gasto_id: int):
  for g in GASTOS:
      if g["id"] == gasto_id:
          return g
  return {"error": "no encontrado"}

# PARÁMETRO DE CONSULTA: filtros opcionales tras ?
# GET /gastos?categoria=comida  ->  categoria = "comida"
@app.get("/gastos")
def listar_gastos(categoria: str | None = None):
  if categoria is None:
      return GASTOS
  return [g for g in GASTOS if g["categoria"] == categoria]

Un PARÁMETRO DE RUTA va entre llaves en la ruta (/gastos/{gasto_id}) y como parámetro tipado de la función (gasto_id: int) —FastAPI lo extrae de la URL y valida que sea un entero (si mandas /gastos/abc, responde error 422 automáticamente)—. Un PARÁMETRO DE CONSULTA es un parámetro de la función que NO está en la ruta (categoria: str | None = None): FastAPI lo lee de la query string (?categoria=comida), y al tener valor por defecto, es opcional. Los type hints hacen la validación: declaras el tipo, FastAPI lo verifica.

Recibir datos en el cuerpo

POST y el cuerpo de la petición

Para CREAR o actualizar, los datos van en el CUERPO de la petición (no en la URL). FastAPI los recibe y valida con un modelo (que verás a fondo con Pydantic en la próxima lección):

crear.py

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# un modelo define la FORMA esperada del cuerpo (Pydantic, próxima lección)
class GastoNuevo(BaseModel):
  nombre: str
  valor: int
  categoria: str = "otros"

GASTOS = []

# POST /gastos con un cuerpo JSON -> FastAPI lo valida contra GastoNuevo
@app.post("/gastos", status_code=201)
def crear_gasto(gasto: GastoNuevo):
  nuevo = {"id": len(GASTOS) + 1, **gasto.model_dump()}
  GASTOS.append(nuevo)
  return nuevo    # devuelve el gasto creado, con su id

terminal

$ curl -X POST http://127.0.0.1:8000/gastos -H "Content-Type: application/json" -d '{"nombre":"Café","valor":4000}'

{"id":1,"nombre":"Café","valor":4000,"categoria":"otros"}

Cuando el endpoint tiene un parámetro cuyo tipo es un modelo (gasto: GastoNuevo), FastAPI espera esos datos en el CUERPO de la petición (JSON) y los VALIDA contra el modelo: si falta nombre o valor no es un número, responde un error 422 detallado —sin que escribas ni una línea de validación—. status_code=201 indica "creado". Este es el corazón de una API: parámetros de ruta para identificar, de consulta para filtrar, y el cuerpo para recibir datos, todo tipado y validado. La próxima lección profundiza en Pydantic, el motor de esa validación.

¿Dónde van los datos en cada caso: identificar un gasto, filtrar una lista, y crear un gasto nuevo?

Mini-reto

Amplía tu API (en tu Python instalado): 1) un endpoint GET /gastos/{gasto_id} que devuelva el gasto con ese id de una lista, o un mensaje de error; 2) GET /gastos con un parámetro de consulta opcional categoria: str | None = None que filtre; 3) POST /gastos que reciba un modelo con nombre y valor y lo agregue a la lista devolviendo el creado con status_code=201. Pruébalos en /docs. Observa cómo FastAPI valida los tipos solo.

Qué sigue

Ya recibes y devuelves datos. La próxima lección profundiza en la pieza que hace la validación: PYDANTIC —los modelos que definen la forma y las reglas de tus datos—. Es el mismo Zod que viste en TypeScript, en su versión Python, y el corazón de por qué FastAPI es tan seguro y cómodo.