Modelo de Response - Tipo de Retorno¶

Puedes declarar el tipo utilizado para el response anotando eltipo de retorno de lapath operation function.

Puedes utilizaranotaciones de tipos de la misma manera que lo harías para datos de entrada enparámetros de función, puedes utilizar modelos de Pydantic, lists, diccionarios, valores escalares como enteros, booleanos, etc.

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:list[str]=[]@app.post("/items/")asyncdefcreate_item(item:Item)->Item:returnitem@app.get("/items/")asyncdefread_items()->list[Item]:return[Item(name="Portal Gun",price=42.0),Item(name="Plumbus",price=32.0),]

FastAPI usará este tipo de retorno para:

• Validar los datos devueltos.
  • Si los datos son inválidos (por ejemplo, falta un campo), significa que el código detu aplicación está defectuoso, no devolviendo lo que debería, y retornará un error del servidor en lugar de devolver datos incorrectos. De esta manera, tú y tus clientes pueden estar seguros de que recibirán los datos y la forma de los datos esperada.
• Agregar unJSON Schema para el response, en lapath operation de OpenAPI.
  • Esto será utilizado por ladocumentación automática.
  • También será utilizado por herramientas de generación automática de código de cliente.

Pero lo más importante:

• Limitará y filtrará los datos de salida a lo que se define en el tipo de retorno.
  • Esto es particularmente importante para laseguridad, veremos más sobre eso a continuación.

Parámetroresponse_model¶

Hay algunos casos en los que necesitas o quieres devolver algunos datos que no son exactamente lo que declara el tipo.

Por ejemplo, podrías quererdevolver un diccionario u objeto de base de datos, perodeclararlo como un modelo de Pydantic. De esta manera el modelo de Pydantic haría toda la documentación de datos, validación, etc. para el objeto que devolviste (por ejemplo, un diccionario u objeto de base de datos).

Si añadiste la anotación del tipo de retorno, las herramientas y editores se quejarían con un error (correcto) diciéndote que tu función está devolviendo un tipo (por ejemplo, un dict) que es diferente de lo que declaraste (por ejemplo, un modelo de Pydantic).

En esos casos, puedes usar el parámetro deldecorador de path operationresponse_model en lugar del tipo de retorno.

Puedes usar el parámetroresponse_model en cualquiera de laspath operations:

• @app.get()
• @app.post()
• @app.put()
• @app.delete()
• etc.

fromtypingimportAnyfromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:list[str]=[]@app.post("/items/",response_model=Item)asyncdefcreate_item(item:Item)->Any:returnitem@app.get("/items/",response_model=list[Item])asyncdefread_items()->Any:return[{"name":"Portal Gun","price":42.0},{"name":"Plumbus","price":32.0},]

response_model recibe el mismo tipo que declararías para un campo de modelo Pydantic, por lo que puede ser un modelo de Pydantic, pero también puede ser, por ejemplo, unlist de modelos de Pydantic, comoList[Item].

FastAPI usará esteresponse_model para hacer toda la documentación de datos, validación, etc. y también paraconvertir y filtrar los datos de salida a su declaración de tipo.

Prioridad delresponse_model¶

Si declaras tanto un tipo de retorno como unresponse_model, elresponse_model tomará prioridad y será utilizado por FastAPI.

De esta manera puedes añadir anotaciones de tipos correctas a tus funciones incluso cuando estás devolviendo un tipo diferente al modelo de response, para ser utilizado por el editor y herramientas como mypy. Y aún así puedes hacer que FastAPI realice la validación de datos, documentación, etc. usando elresponse_model.

También puedes usarresponse_model=None para desactivar la creación de un modelo de response para esapath operation, podrías necesitar hacerlo si estás añadiendo anotaciones de tipos para cosas que no son campos válidos de Pydantic, verás un ejemplo de eso en una de las secciones a continuación.

Devolver los mismos datos de entrada¶

Aquí estamos declarando un modeloUserIn, contendrá una contraseña en texto plano:

fromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=None# Don't do this in production!@app.post("/user/")asyncdefcreate_user(user:UserIn)->UserIn:returnuser

$pipinstallemail-validator

$pipinstall"pydantic[email]"

Y estamos usando este modelo para declarar nuestra entrada y el mismo modelo para declarar nuestra salida:

fromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=None# Don't do this in production!@app.post("/user/")asyncdefcreate_user(user:UserIn)->UserIn:returnuser

Ahora, cada vez que un navegador esté creando un usuario con una contraseña, la API devolverá la misma contraseña en el response.

En este caso, podría no ser un problema, porque es el mismo usuario que envía la contraseña.

Pero si usamos el mismo modelo para otrapath operation, podríamos estar enviando las contraseñas de nuestros usuarios a cada cliente.

Añadir un modelo de salida¶

Podemos en cambio crear un modelo de entrada con la contraseña en texto plano y un modelo de salida sin ella:

fromtypingimportAnyfromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=NoneclassUserOut(BaseModel):username:stremail:EmailStrfull_name:str|None=None@app.post("/user/",response_model=UserOut)asyncdefcreate_user(user:UserIn)->Any:returnuser

Aquí, aunque nuestrapath operation function está devolviendo el mismo usuario de entrada que contiene la contraseña:

fromtypingimportAnyfromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=NoneclassUserOut(BaseModel):username:stremail:EmailStrfull_name:str|None=None@app.post("/user/",response_model=UserOut)asyncdefcreate_user(user:UserIn)->Any:returnuser

...hemos declarado elresponse_model para ser nuestro modeloUserOut, que no incluye la contraseña:

fromtypingimportAnyfromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classUserIn(BaseModel):username:strpassword:stremail:EmailStrfull_name:str|None=NoneclassUserOut(BaseModel):username:stremail:EmailStrfull_name:str|None=None@app.post("/user/",response_model=UserOut)asyncdefcreate_user(user:UserIn)->Any:returnuser

Entonces,FastAPI se encargará de filtrar todos los datos que no estén declarados en el modelo de salida (usando Pydantic).

response_model o Tipo de Retorno¶

En este caso, como los dos modelos son diferentes, si anotáramos el tipo de retorno de la función comoUserOut, el editor y las herramientas se quejarían de que estamos devolviendo un tipo inválido, ya que son clases diferentes.

Por eso en este ejemplo tenemos que declararlo en el parámetroresponse_model.

...pero sigue leyendo abajo para ver cómo superar eso.

Tipo de Retorno y Filtrado de Datos¶

Continuemos con el ejemplo anterior. Queríamosanotar la función con un tipo, pero queríamos poder devolver desde la función algo que en realidad incluyamás datos.

Queremos que FastAPI continúefiltrando los datos usando el modelo de response. Para que, incluso cuando la función devuelva más datos, el response solo incluya los campos declarados en el modelo de response.

En el ejemplo anterior, debido a que las clases eran diferentes, tuvimos que usar el parámetroresponse_model. Pero eso también significa que no obtenemos el soporte del editor y las herramientas verificando el tipo de retorno de la función.

Pero en la mayoría de los casos en los que necesitamos hacer algo como esto, queremos que el modelo solofiltre/elimine algunos de los datos como en este ejemplo.

Y en esos casos, podemos usar clases y herencia para aprovechar lasanotaciones de tipos de funciones para obtener mejor soporte en el editor y herramientas, y aún así obtener elfiltrado de datos de FastAPI.

fromfastapiimportFastAPIfrompydanticimportBaseModel,EmailStrapp=FastAPI()classBaseUser(BaseModel):username:stremail:EmailStrfull_name:str|None=NoneclassUserIn(BaseUser):password:str@app.post("/user/")asyncdefcreate_user(user:UserIn)->BaseUser:returnuser

Con esto, obtenemos soporte de las herramientas, de los editores y mypy ya que este código es correcto en términos de tipos, pero también obtenemos el filtrado de datos de FastAPI.

¿Cómo funciona esto? Vamos a echarle un vistazo. 🤓

Anotaciones de Tipos y Herramientas¶

Primero vamos a ver cómo los editores, mypy y otras herramientas verían esto.

BaseUser tiene los campos base. LuegoUserIn hereda deBaseUser y añade el campopassword, por lo que incluirá todos los campos de ambos modelos.

Anotamos el tipo de retorno de la función comoBaseUser, pero en realidad estamos devolviendo unUserIn instance.

El editor, mypy y otras herramientas no se quejarán de esto porque, en términos de tipificación,UserIn es una subclase deBaseUser, lo que significa que es un tipoválido cuando se espera algo que es unBaseUser.

Filtrado de Datos en FastAPI¶

Ahora, para FastAPI, verá el tipo de retorno y se asegurará de que lo que devuelves incluyasolo los campos que están declarados en el tipo.

FastAPI realiza varias cosas internamente con Pydantic para asegurarse de que esas mismas reglas de herencia de clases no se utilicen para el filtrado de datos devueltos, de lo contrario, podrías terminar devolviendo muchos más datos de los que esperabas.

De esta manera, puedes obtener lo mejor de ambos mundos: anotaciones de tipos consoporte de herramientas yfiltrado de datos.

Verlo en la documentación¶

Cuando veas la documentación automática, puedes verificar que el modelo de entrada y el modelo de salida tendrán cada uno su propio JSON Schema:

Y ambos modelos se utilizarán para la documentación interactiva de la API:

Otras Anotaciones de Tipos de Retorno¶

Podría haber casos en los que devuelvas algo que no es un campo válido de Pydantic y lo anotes en la función, solo para obtener el soporte proporcionado por las herramientas (el editor, mypy, etc).

Devolver un Response Directamente¶

El caso más común seríadevolver un Response directamente como se explica más adelante en la documentación avanzada.

fromfastapiimportFastAPI,Responsefromfastapi.responsesimportJSONResponse,RedirectResponseapp=FastAPI()@app.get("/portal")asyncdefget_portal(teleport:bool=False)->Response:ifteleport:returnRedirectResponse(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")returnJSONResponse(content={"message":"Here's your interdimensional portal."})

Este caso simple es manejado automáticamente por FastAPI porque la anotación del tipo de retorno es la clase (o una subclase de)Response.

Y las herramientas también estarán felices porque tantoRedirectResponse comoJSONResponse son subclases deResponse, por lo que la anotación del tipo es correcta.

Anotar una Subclase de Response¶

También puedes usar una subclase deResponse en la anotación del tipo:

fromfastapiimportFastAPIfromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/teleport")asyncdefget_teleport()->RedirectResponse:returnRedirectResponse(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")

Esto también funcionará porqueRedirectResponse es una subclase deResponse, y FastAPI manejará automáticamente este caso simple.

Anotaciones de Tipos de Retorno Inválidas¶

Pero cuando devuelves algún otro objeto arbitrario que no es un tipo válido de Pydantic (por ejemplo, un objeto de base de datos) y lo anotas así en la función, FastAPI intentará crear un modelo de response de Pydantic a partir de esa anotación de tipo, y fallará.

Lo mismo sucedería si tuvieras algo como unaunión entre diferentes tipos donde uno o más de ellos no son tipos válidos de Pydantic, por ejemplo esto fallaría 💥:

fromfastapiimportFastAPI,Responsefromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/portal")asyncdefget_portal(teleport:bool=False)->Response|dict:ifteleport:returnRedirectResponse(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")return{"message":"Here's your interdimensional portal."}

...esto falla porque la anotación de tipo no es un tipo de Pydantic y no es solo una sola claseResponse o subclase, es una unión (cualquiera de los dos) entre unaResponse y undict.

Desactivar el Modelo de Response¶

Continuando con el ejemplo anterior, puede que no quieras tener la validación de datos por defecto, documentación, filtrado, etc. que realiza FastAPI.

Pero puedes querer mantener la anotación del tipo de retorno en la función para obtener el soporte de herramientas como editores y verificadores de tipos (por ejemplo, mypy).

En este caso, puedes desactivar la generación del modelo de response configurandoresponse_model=None:

fromfastapiimportFastAPI,Responsefromfastapi.responsesimportRedirectResponseapp=FastAPI()@app.get("/portal",response_model=None)asyncdefget_portal(teleport:bool=False)->Response|dict:ifteleport:returnRedirectResponse(url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")return{"message":"Here's your interdimensional portal."}

Esto hará que FastAPI omita la generación del modelo de response y de esa manera puedes tener cualquier anotación de tipo de retorno que necesites sin que afecte a tu aplicación FastAPI. 🤓

Parámetros de codificación del Modelo de Response¶

Tu modelo de response podría tener valores por defecto, como:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float=10.5tags:list[str]=[]items={"foo":{"name":"Foo","price":50.2},"bar":{"name":"Bar","description":"The bartenders","price":62,"tax":20.2},"baz":{"name":"Baz","description":None,"price":50.2,"tax":10.5,"tags":[]},}@app.get("/items/{item_id}",response_model=Item,response_model_exclude_unset=True)asyncdefread_item(item_id:str):returnitems[item_id]

• description: Union[str, None] = None (ostr | None = None en Python 3.10) tiene un valor por defecto deNone.
• tax: float = 10.5 tiene un valor por defecto de10.5.
• tags: List[str] = [] tiene un valor por defecto de una list vacía:[].

pero podrías querer omitirlos del resultado si no fueron en realidad almacenados.

Por ejemplo, si tienes modelos con muchos atributos opcionales en una base de datos NoSQL, pero no quieres enviar responses JSON muy largos llenos de valores por defecto.

Usa el parámetroresponse_model_exclude_unset¶

Puedes configurar el parámetro del decorador de path operationresponse_model_exclude_unset=True:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float=10.5tags:list[str]=[]items={"foo":{"name":"Foo","price":50.2},"bar":{"name":"Bar","description":"The bartenders","price":62,"tax":20.2},"baz":{"name":"Baz","description":None,"price":50.2,"tax":10.5,"tags":[]},}@app.get("/items/{item_id}",response_model=Item,response_model_exclude_unset=True)asyncdefread_item(item_id:str):returnitems[item_id]

y esos valores por defecto no serán incluidos en el response, solo los valores realmente establecidos.

Entonces, si envías un request a esapath operation para el ítem con IDfoo, el response (no incluyendo valores por defecto) será:

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

Datos con valores para campos con valores por defecto¶

Pero si tus datos tienen valores para los campos del modelo con valores por defecto, como el artículo con IDbar:

{"name":"Bar","description":"The bartenders","price":62,"tax":20.2}

serán incluidos en el response.

Datos con los mismos valores que los valores por defecto¶

Si los datos tienen los mismos valores que los valores por defecto, como el artículo con IDbaz:

{"name":"Baz","description":None,"price":50.2,"tax":10.5,"tags":[]}

FastAPI es lo suficientemente inteligente (de hecho, Pydantic es lo suficientemente inteligente) para darse cuenta de que, a pesar de quedescription,tax ytags tienen los mismos valores que los valores por defecto, fueron establecidos explícitamente (en lugar de tomados de los valores por defecto).

Por lo tanto, se incluirán en el response JSON.

response_model_include yresponse_model_exclude¶

También puedes usar los parámetros del decorador de path operationresponse_model_include yresponse_model_exclude.

Aceptan unset destr con el nombre de los atributos a incluir (omitiendo el resto) o excluir (incluyendo el resto).

Esto se puede usar como un atajo rápido si solo tienes un modelo de Pydantic y quieres eliminar algunos datos de la salida.

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float=10.5items={"foo":{"name":"Foo","price":50.2},"bar":{"name":"Bar","description":"The Bar fighters","price":62,"tax":20.2},"baz":{"name":"Baz","description":"There goes my baz","price":50.2,"tax":10.5,},}@app.get("/items/{item_id}/name",response_model=Item,response_model_include={"name","description"},)asyncdefread_item_name(item_id:str):returnitems[item_id]@app.get("/items/{item_id}/public",response_model=Item,response_model_exclude={"tax"})asyncdefread_item_public_data(item_id:str):returnitems[item_id]

Usarlists en lugar desets¶

Si olvidas usar unset y usas unlist otuple en su lugar, FastAPI todavía lo convertirá a unset y funcionará correctamente:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float=10.5items={"foo":{"name":"Foo","price":50.2},"bar":{"name":"Bar","description":"The Bar fighters","price":62,"tax":20.2},"baz":{"name":"Baz","description":"There goes my baz","price":50.2,"tax":10.5,},}@app.get("/items/{item_id}/name",response_model=Item,response_model_include=["name","description"],)asyncdefread_item_name(item_id:str):returnitems[item_id]@app.get("/items/{item_id}/public",response_model=Item,response_model_exclude=["tax"])asyncdefread_item_public_data(item_id:str):returnitems[item_id]

Resumen¶

Usa el parámetroresponse_model deldecorador de path operation para definir modelos de response y especialmente para asegurarte de que los datos privados sean filtrados.

Usaresponse_model_exclude_unset para devolver solo los valores establecidos explícitamente.