Parámetros de Path¶

Puedes declarar "parámetros" o "variables" de path con la misma sintaxis que se usa en los format strings de Python:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_item(item_id):return{"item_id":item_id}

El valor del parámetro de pathitem_id se pasará a tu función como el argumentoitem_id.

Así que, si ejecutas este ejemplo y vas ahttp://127.0.0.1:8000/items/foo, verás un response de:

{"item_id":"foo"}

Parámetros de path con tipos¶

Puedes declarar el tipo de un parámetro de path en la función, usando anotaciones de tipos estándar de Python:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_item(item_id:int):return{"item_id":item_id}

En este caso,item_id se declara como unint.

Conversión de datos¶

Si ejecutas este ejemplo y abres tu navegador enhttp://127.0.0.1:8000/items/3, verás un response de:

{"item_id":3}

Validación de datos¶

Pero si vas al navegador enhttp://127.0.0.1:8000/items/foo, verás un bonito error HTTP de:

{"detail":[{"type":"int_parsing","loc":["path","item_id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"foo"}]}

porque el parámetro de pathitem_id tenía un valor de"foo", que no es unint.

El mismo error aparecería si proporcionaras unfloat en lugar de unint, como en:http://127.0.0.1:8000/items/4.2

Documentación¶

Y cuando abras tu navegador enhttp://127.0.0.1:8000/docs, verás una documentación de API automática e interactiva como:

Beneficios basados en estándares, documentación alternativa¶

Y porque el esquema generado es del estándarOpenAPI, hay muchas herramientas compatibles.

Debido a esto, el propioFastAPI proporciona una documentación de API alternativa (usando ReDoc), a la cual puedes acceder enhttp://127.0.0.1:8000/redoc:

De la misma manera, hay muchas herramientas compatibles. Incluyendo herramientas de generación de código para muchos lenguajes.

Pydantic¶

Toda la validación de datos se realiza internamente conPydantic, así que obtienes todos los beneficios de esta. Y sabes que estás en buenas manos.

Puedes usar las mismas declaraciones de tipo constr,float,bool y muchos otros tipos de datos complejos.

Varios de estos se exploran en los siguientes capítulos del tutorial.

El orden importa¶

Al crearpath operations, puedes encontrarte en situaciones donde tienes un path fijo.

Como/users/me, imaginemos que es para obtener datos sobre el usuario actual.

Y luego también puedes tener un path/users/{user_id} para obtener datos sobre un usuario específico por algún ID de usuario.

Debido a que laspath operations se evalúan en orden, necesitas asegurarte de que el path para/users/me se declara antes que el de/users/{user_id}:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/users/me")asyncdefread_user_me():return{"user_id":"the current user"}@app.get("/users/{user_id}")asyncdefread_user(user_id:str):return{"user_id":user_id}

De lo contrario, el path para/users/{user_id} también coincidiría para/users/me, "pensando" que está recibiendo un parámetrouser_id con un valor de"me".

De manera similar, no puedes redefinir una path operation:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/users")asyncdefread_users():return["Rick","Morty"]@app.get("/users")asyncdefread_users2():return["Bean","Elfo"]

La primera siempre será utilizada ya que el path coincide primero.

Valores predefinidos¶

Si tienes unapath operation que recibe unpath parameter, pero quieres que los valores posibles válidos delpath parameter estén predefinidos, puedes usar unEnum estándar de Python.

Crear una claseEnum¶

ImportaEnum y crea una subclase que herede destr y deEnum.

Al heredar destr, la documentación de la API podrá saber que los valores deben ser de tipostring y podrá representarlos correctamente.

Luego crea atributos de clase con valores fijos, que serán los valores válidos disponibles:

fromenumimportEnumfromfastapiimportFastAPIclassModelName(str,Enum):alexnet="alexnet"resnet="resnet"lenet="lenet"app=FastAPI()@app.get("/models/{model_name}")asyncdefget_model(model_name:ModelName):ifmodel_nameisModelName.alexnet:return{"model_name":model_name,"message":"Deep Learning FTW!"}ifmodel_name.value=="lenet":return{"model_name":model_name,"message":"LeCNN all the images"}return{"model_name":model_name,"message":"Have some residuals"}

Declarar unpath parameter¶

Luego crea unpath parameter con una anotación de tipo usando la clase enum que creaste (ModelName):

fromenumimportEnumfromfastapiimportFastAPIclassModelName(str,Enum):alexnet="alexnet"resnet="resnet"lenet="lenet"app=FastAPI()@app.get("/models/{model_name}")asyncdefget_model(model_name:ModelName):ifmodel_nameisModelName.alexnet:return{"model_name":model_name,"message":"Deep Learning FTW!"}ifmodel_name.value=="lenet":return{"model_name":model_name,"message":"LeCNN all the images"}return{"model_name":model_name,"message":"Have some residuals"}

Revisa la documentación¶

Como los valores disponibles para elpath parameter están predefinidos, la documentación interactiva puede mostrarlos de manera ordenada:

Trabajando conenumeraciones de Python¶

El valor delpath parameter será unmiembro de enumeración.

Compararmiembros de enumeraciones¶

Puedes compararlo con elmiembro de enumeración en tu enum creadaModelName:

fromenumimportEnumfromfastapiimportFastAPIclassModelName(str,Enum):alexnet="alexnet"resnet="resnet"lenet="lenet"app=FastAPI()@app.get("/models/{model_name}")asyncdefget_model(model_name:ModelName):ifmodel_nameisModelName.alexnet:return{"model_name":model_name,"message":"Deep Learning FTW!"}ifmodel_name.value=="lenet":return{"model_name":model_name,"message":"LeCNN all the images"}return{"model_name":model_name,"message":"Have some residuals"}

Obtener el valor deenumeración¶

Puedes obtener el valor actual (unstr en este caso) usandomodel_name.value, o en general,your_enum_member.value:

fromenumimportEnumfromfastapiimportFastAPIclassModelName(str,Enum):alexnet="alexnet"resnet="resnet"lenet="lenet"app=FastAPI()@app.get("/models/{model_name}")asyncdefget_model(model_name:ModelName):ifmodel_nameisModelName.alexnet:return{"model_name":model_name,"message":"Deep Learning FTW!"}ifmodel_name.value=="lenet":return{"model_name":model_name,"message":"LeCNN all the images"}return{"model_name":model_name,"message":"Have some residuals"}

Devolvermiembros de enumeración¶

Puedes devolvermiembros de enum desde tupath operation, incluso anidados en un cuerpo JSON (por ejemplo, undict).

Serán convertidos a sus valores correspondientes (cadenas en este caso) antes de devolverlos al cliente:

fromenumimportEnumfromfastapiimportFastAPIclassModelName(str,Enum):alexnet="alexnet"resnet="resnet"lenet="lenet"app=FastAPI()@app.get("/models/{model_name}")asyncdefget_model(model_name:ModelName):ifmodel_nameisModelName.alexnet:return{"model_name":model_name,"message":"Deep Learning FTW!"}ifmodel_name.value=="lenet":return{"model_name":model_name,"message":"LeCNN all the images"}return{"model_name":model_name,"message":"Have some residuals"}

En tu cliente recibirás un response JSON como:

{"model_name":"alexnet","message":"Deep Learning FTW!"}

Parámetros de path conteniendo paths¶

Imaginemos que tienes unapath operation con un path/files/{file_path}.

Pero necesitas quefile_path en sí mismo contenga unpath, comohome/johndoe/myfile.txt.

Entonces, la URL para ese archivo sería algo como:/files/home/johndoe/myfile.txt.

Soporte de OpenAPI¶

OpenAPI no soporta una manera de declarar unpath parameter para que contenga unpath dentro, ya que eso podría llevar a escenarios que son difíciles de probar y definir.

Sin embargo, todavía puedes hacerlo enFastAPI, usando una de las herramientas internas de Starlette.

Y la documentación seguiría funcionando, aunque no agregue ninguna documentación indicando que el parámetro debe contener un path.

Convertidor de Path¶

Usando una opción directamente de Starlette puedes declarar unpath parameter conteniendo unpath usando una URL como:

/files/{file_path:path}

En este caso, el nombre del parámetro esfile_path, y la última parte,:path, indica que el parámetro debería coincidir con cualquierpath.

Así que, puedes usarlo con:

fromfastapiimportFastAPIapp=FastAPI()@app.get("/files/{file_path:path}")asyncdefread_file(file_path:str):return{"file_path":file_path}

Resumen¶

ConFastAPI, al usar declaraciones de tipo estándar de Python, cortas e intuitivas, obtienes:

• Soporte del editor: chequeo de errores, autocompletado, etc.
• "parsing " de datos
• Validación de datos
• Anotación de API y documentación automática

Y solo tienes que declararlos una vez.

Probablemente esa sea la principal ventaja visible deFastAPI en comparación con otros frameworks alternativos (aparte del rendimiento bruto).