¿Cómo recibes un cuerpo de solicitud JSON?

Question

Accepted Answer

Para recibir un cuerpo de solicitud JSON en FastAPI, declaras un parámetro de función tipado como un **modelo Pydantic**. FastAPI lee el cuerpo, analiza el JSON, lo valida contra el modelo y te pasa un objeto tipado — automáticamente.

## El patrón

```python
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None      # optional field

@app.post("/items")
def create_item(item: Item):             # `item: Item` → read & validate the JSON body
    # `item` is a fully-validated Item object here
    return {"name": item.name, "total": item.price * 1.1}
```

```json
// request body the client sends:
{ "name": "Phone", "price": 999.0 }
```

Declarar `item: Item` le indica a FastAPI que lea el cuerpo de la solicitud como JSON, lo analice en un `Item` y lo **valide** — tu función recibe un objeto tipado y válido. La entrada incorrecta se rechaza automáticamente:

```json
// POST { "name": "Phone" }  (missing price) → automatic 422:
{ "detail": [{ "loc": ["body", "price"], "msg": "field required" }] }
```

## Cuerpo + ruta + consulta juntos

```python
@app.put("/items/{item_id}")
def update(item_id: int, item: Item, notify: bool = False):
    # item_id = path param, item = JSON body (Pydantic model), notify = query param
    # FastAPI distinguishes them by type/location automatically
```

FastAPI enruta parámetros de forma inteligente: un marcador de posición de ruta → parámetro de ruta, un modelo Pydantic → cuerpo de solicitud, un parámetro de tipo simple → parámetro de consulta.

## Múltiples parámetros de cuerpo / actualizaciones parciales

```python
@app.patch("/items/{id}")
def patch(id: int, item: ItemUpdate):       # use a model with all-optional fields for PATCH
    update_data = item.model_dump(exclude_unset=True)   # only fields the client sent
```

## Por qué es importante

Recibir y validar cuerpos de solicitud es esencial — casi toda API que crea o actualiza datos lo necesita, y FastAPI lo hace notablemente limpio: declarar un parámetro de modelo Pydantic te da análisis JSON automático, **validación** completa (con errores claros de nivel de campo 422) y un objeto tipado, eliminando el análisis manual tedioso y propenso a errores y la validación que requieren otros frameworks.

La validación también es un beneficio clave de **seguridad/robustez** — la entrada mal formada se rechaza antes de llegar a tu lógica.

Comprender cómo definir un modelo de cuerpo, cómo FastAPI distingue automáticamente el cuerpo de los parámetros de ruta/consulta, y patrones como `exclude_unset` para actualizaciones parciales es conocimiento fundamental cotidiano para crear cualquier endpoint de escritura.