Request Body¶

Cuando necesitas enviar datos desde un cliente (digamos, un navegador) a tu API, los envías como unrequest body.

Unrequest body es un dato enviado por el cliente a tu API. Unresponse body es el dato que tu API envía al cliente.

Tu API casi siempre tiene que enviar unresponse body. Pero los clientes no necesariamente necesitan enviarrequest bodies todo el tiempo, a veces solo solicitan un path, quizás con algunos parámetros de query, pero no envían un body.

Para declarar unrequest body, usas modelos dePydantic con todo su poder y beneficios.

ImportarBaseModel de Pydantic¶

Primero, necesitas importarBaseModel depydantic:

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.post("/items/")asyncdefcreate_item(item:Item):returnitem

Crea tu modelo de datos¶

Luego, declaras tu modelo de datos como una clase que hereda deBaseModel.

Usa tipos estándar de Python para todos los atributos:

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.post("/items/")asyncdefcreate_item(item:Item):returnitem

Al igual que al declarar parámetros de query, cuando un atributo del modelo tiene un valor por defecto, no es obligatorio. De lo contrario, es obligatorio. UsaNone para hacerlo solo opcional.

Por ejemplo, el modelo anterior declara un “object” JSON (odict en Python) como:

{"name":"Foo","description":"An optional description","price":45.2,"tax":3.5}

...dado quedescription ytax son opcionales (con un valor por defecto deNone), este “object” JSON también sería válido:

{"name":"Foo","price":45.2}

Decláralo como un parámetro¶

Para añadirlo a tupath operation, decláralo de la misma manera que declaraste parámetros de path y query:

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.post("/items/")asyncdefcreate_item(item:Item):returnitem

...y declara su tipo como el modelo que creaste,Item.

Resultados¶

Con solo esa declaración de tipo en Python,FastAPI hará lo siguiente:

• Leer el body del request como JSON.
• Convertir los tipos correspondientes (si es necesario).
• Validar los datos.
  • Si los datos son inválidos, devolverá un error claro e indicado, señalando exactamente dónde y qué fue lo incorrecto.
• Proporcionar los datos recibidos en el parámetroitem.
  • Como lo declaraste en la función como de tipoItem, también tendrás todo el soporte del editor (autocompletado, etc.) para todos los atributos y sus tipos.
• Generar definiciones deJSON Schema para tu modelo, que también puedes usar en cualquier otro lugar si tiene sentido para tu proyecto.
• Esos esquemas serán parte del esquema de OpenAPI generado y usados por lasUIs de documentación automática.

Documentación automática¶

Los JSON Schemas de tus modelos serán parte del esquema OpenAPI generado y se mostrarán en la documentación API interactiva:

Y también se utilizarán en la documentación API dentro de cadapath operation que los necesite:

Soporte del editor¶

En tu editor, dentro de tu función, obtendrás anotaciones de tipos y autocompletado en todas partes (esto no sucedería si recibieras undict en lugar de un modelo de Pydantic):

También recibirás chequeos de errores para operaciones de tipo incorrecto:

No es por casualidad, todo el framework fue construido alrededor de ese diseño.

Y fue rigurosamente probado en la fase de diseño, antes de cualquier implementación, para garantizar que funcionaría con todos los editores.

Incluso se hicieron algunos cambios en Pydantic para admitir esto.

Las capturas de pantalla anteriores se tomaron conVisual Studio Code.

Pero obtendrías el mismo soporte en el editor conPyCharm y la mayoría de los otros editores de Python:

Usa el modelo¶

Dentro de la función, puedes acceder a todos los atributos del objeto modelo directamente:

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.post("/items/")asyncdefcreate_item(item:Item):item_dict=item.model_dump()ifitem.taxisnotNone:price_with_tax=item.price+item.taxitem_dict.update({"price_with_tax":price_with_tax})returnitem_dict

Request body + parámetros de path¶

Puedes declarar parámetros de path y request body al mismo tiempo.

FastAPI reconocerá que los parámetros de función que coinciden con los parámetros de path deben sertomados del path, y que los parámetros de función que se declaran como modelos de Pydantic deben sertomados del request body.

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):return{"item_id":item_id,**item.model_dump()}

Request body + path + parámetros de query¶

También puedes declarar parámetros debody,path yquery, todos al mismo tiempo.

FastAPI reconocerá cada uno de ellos y tomará los datos del lugar correcto.

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Noneapp=FastAPI()@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item,q:str|None=None):result={"item_id":item_id,**item.model_dump()}ifq:result.update({"q":q})returnresult

Los parámetros de la función se reconocerán de la siguiente manera:

• Si el parámetro también se declara en elpath, se utilizará como un parámetro de path.
• Si el parámetro es de untipo singular (comoint,float,str,bool, etc.), se interpretará como un parámetro dequery.
• Si el parámetro se declara como del tipo de unmodelo de Pydantic, se interpretará como unbody de request.

Sin Pydantic¶

Si no quieres usar modelos de Pydantic, también puedes usar parámetrosBody. Consulta la documentación paraBody - Múltiples parámetros: Valores singulares en el body.