Como você recebe um corpo de solicitação JSON?

Question

Accepted Answer

Para receber um corpo de solicitação JSON no FastAPI, você declara um parâmetro de função digitado como um **modelo Pydantic**. FastAPI lê o corpo, analisa o JSON, valida contra o modelo e passa um objeto digitado — automaticamente.

## O padrão

```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` diz ao FastAPI para ler o corpo da solicitação como JSON, analisá-lo em um `Item`, e **validar** — sua função recebe um objeto digitado e válido. Entrada incorreta é rejeitada automaticamente:

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

## Corpo + caminho + 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 roteia parâmetros inteligentemente: um espaço reservado de caminho → parâmetro de caminho, um modelo Pydantic → corpo da solicitação, um parâmetro digitado simples → parâmetro de consulta.

## Múltiplos parâmetros de corpo / atualizações parciais

```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 que isso importa

Receber e validar corpos de solicitação é essencial — quase todo API que cria ou atualiza dados precisa disso, e FastAPI torna isso notavelmente limpo: declarar um parâmetro de modelo Pydantic fornece análise JSON automática, **validação** completa (com erros claros em nível de campo 422), e um objeto digitado, eliminando a análise manual tediosa e propensa a erros e validação que outros frameworks exigem.

A validação também é um benefício importante de **segurança/robustez** — entradas malformadas são rejeitadas antes de atingir sua lógica.

Entender como definir um modelo de corpo, como FastAPI distingue automaticamente corpo de parâmetros de caminho/consulta, e padrões como `exclude_unset` para atualizações parciais é conhecimento fundamental do dia a dia para construir qualquer endpoint de escrita.