Primeros Pasos¶
El archivo FastAPI más simple podría verse así:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Copia eso a un archivo main.py.
Ejecuta el servidor en vivo:
fastapi dev
FastAPI Starting development server 🚀
Searching for package file structure from directories
with __init__.py files
Importing from /home/user/code/awesomeapp
module 🐍 main.py
code Importing the FastAPI app object from the module with
the following code:
from main import app
app Using import string: main:app
server Server started at http://127.0.0.1:8000
server Documentation at http://127.0.0.1:8000/docs
tip Running in development mode, for production use:
fastapi run
Logs:
INFO Will watch for changes in these directories:
['/home/user/code/awesomeapp']
INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C
to quit)
INFO Started reloader process [383138] using WatchFiles
INFO Started server process [383153]
INFO Waiting for application startup.
INFO Application startup complete.
restart ↻En la salida, hay una línea con algo como:
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Esa línea muestra la URL donde tu app está siendo servida en tu máquina local.
Revísalo¶
Abre tu navegador en http://127.0.0.1:8000.
Verás la respuesta JSON como:
{"message": "Hello World"}
Documentación interactiva de la API¶
Ahora ve a http://127.0.0.1:8000/docs.
Verás la documentación interactiva automática de la API (proporcionada por Swagger UI):
Documentación alternativa de la API¶
Y ahora, ve a http://127.0.0.1:8000/redoc.
Verás la documentación alternativa automática (proporcionada por ReDoc):
OpenAPI¶
FastAPI genera un "schema" con toda tu API usando el estándar OpenAPI para definir APIs.
"Schema"¶
Un "schema" es una definición o descripción de algo. No el código que lo implementa, sino simplemente una descripción abstracta.
"Schema" de API¶
En este caso, OpenAPI es una especificación que dicta cómo definir un schema de tu API.
Esta definición de schema incluye las rutas de tu API, los posibles parámetros que reciben, etc.
"Schema" de datos¶
El término "schema" también puede referirse a la estructura de algunos datos, como un contenido JSON.
En ese caso, significaría los atributos JSON, y los tipos de datos que tienen, etc.
OpenAPI y JSON Schema¶
OpenAPI define un schema de API para tu API. Y ese schema incluye definiciones (o "schemas") de los datos enviados y recibidos por tu API usando JSON Schema, el estándar para schemas de datos JSON.
Revisar el openapi.json¶
Si tienes curiosidad sobre cómo se ve el schema crudo de OpenAPI, FastAPI genera automáticamente un JSON (schema) con las descripciones de toda tu API.
Puedes verlo directamente en: http://127.0.0.1:8000/openapi.json.
Mostrará un JSON comenzando con algo como:
{
"openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
},
"paths": {
"/items/": {
"get": {
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
...
Para qué sirve OpenAPI¶
El schema de OpenAPI es lo que impulsa los dos sistemas de documentación interactiva incluidos.
Y hay docenas de alternativas, todas basadas en OpenAPI. Podrías añadir fácilmente cualquiera de esas alternativas a tu aplicación construida con FastAPI.
También podrías usarlo para generar código automáticamente, para clientes que se comunican con tu API. Por ejemplo, aplicaciones frontend, móviles o IoT.
Configurar el entrypoint de la aplicación en pyproject.toml¶
Puedes configurar dónde se encuentra tu aplicación en un archivo pyproject.toml así:
[tool.fastapi]
entrypoint = "main:app"
Ese entrypoint le indicará al comando fastapi que debe importar la aplicación así:
from main import app
Si tu código estaba estructurado así:
.
├── backend
│ ├── main.py
│ ├── __init__.py
Luego configurarías el entrypoint como:
[tool.fastapi]
entrypoint = "backend.main:app"
lo cual sería equivalente a:
from backend.main import app
fastapi dev con ruta o con la opción --entrypoint del CLI¶
También puedes pasar la ruta del archivo al comando fastapi dev, y adivinará el objeto de la aplicación FastAPI a usar:
$ fastapi dev main.py
O, también puedes pasar la opción --entrypoint al comando fastapi dev:
$ fastapi dev --entrypoint main:app
Pero tendrías que recordar pasar la ruta\entrypoint correcta cada vez que llames al comando fastapi.
Además, es posible que otras herramientas no puedan encontrarlo, por ejemplo la Extensión de VS Code o FastAPI Cloud, por lo que se recomienda usar el entrypoint en pyproject.toml.
Despliega tu app (opcional)¶
Opcionalmente puedes desplegar tu app FastAPI a FastAPI Cloud con un solo comando. 🚀
El CLI detectará automáticamente tu aplicación FastAPI y la desplegará en la nube. Si no has iniciado sesión, tu navegador se abrirá para completar el proceso de autenticación.
¡Eso es todo! Ahora puedes acceder a tu app en esa URL. ✨
Resumen, paso a paso¶
Paso 1: importar FastAPI¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
FastAPI es una clase de Python que proporciona toda la funcionalidad para tu API.
Detalles Técnicos
FastAPI es una clase que hereda directamente de Starlette.
Puedes usar toda la funcionalidad de Starlette con FastAPI también.
Paso 2: crear una "instancia" de FastAPI¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Aquí la variable app será una "instancia" de la clase FastAPI.
Este será el principal punto de interacción para crear toda tu API.
Paso 3: crear un path operation¶
Path¶
"Path" aquí se refiere a la última parte de la URL comenzando desde el primer /.
Así, en una URL como:
https://example.com/items/foo
...el path sería:
/items/foo
Nota
Un "path" también se llama comúnmente un "endpoint" o una "ruta".
Al construir una API, el "path" es la forma principal de separar "concerns" y "resources".
Operation¶
"Operation" aquí se refiere a uno de los "methods" HTTP.
Uno de:
POSTGETPUTDELETE
...y los más exóticos:
OPTIONSHEADPATCHTRACE
En el protocolo HTTP, puedes comunicarte a cada path usando uno (o más) de estos "methods".
Al construir APIs, normalmente usas estos methods HTTP específicos para realizar una acción específica.
Normalmente usas:
POST: para crear datos.GET: para leer datos.PUT: para actualizar datos.DELETE: para eliminar datos.
Así, en OpenAPI, cada uno de los methods HTTP es llamado una "operation".
También vamos a llamarlos "operations".
Definir un path operation decorator¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
El @app.get("/") le dice a FastAPI que la función justo debajo se encarga de manejar los requests que van a:
- el path
/ - usando una
getoperation
Info sobre @decorator
Esa sintaxis de @something en Python se llama un "decorator".
Lo pones encima de una función. Como un sombrero decorativo bonito (supongo que de ahí viene el término).
Un "decorator" toma la función de abajo y hace algo con ella.
En nuestro caso, este decorator le dice a FastAPI que la función de abajo corresponde al path / con una operation get.
Es el "path operation decorator".
También puedes usar las otras operations:
@app.post()@app.put()@app.delete()
Y las más exóticas:
@app.options()@app.head()@app.patch()@app.trace()
Consejo
Eres libre de usar cada operation (HTTP method) como desees.
FastAPI no impone ningún significado específico.
La información aquí se presenta como una guía, no como un requisito.
Por ejemplo, cuando usas GraphQL normalmente realizas todas las acciones usando solo operations POST.
Paso 4: definir la path operation function¶
Esta es nuestra "path operation function":
- path: es
/. - operation: es
get. - function: es la función debajo del "decorator" (debajo de
@app.get("/")).
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Esta es una función de Python.
Será llamada por FastAPI siempre que reciba un request a la URL "/" usando una operation GET.
En este caso, es una función async.
También podrías definirla como una función normal en lugar de async def:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def root():
return {"message": "Hello World"}
Nota
Si no conoces la diferencia, revisa el Async: "¿Con prisa?".
Paso 5: devolver el contenido¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Puedes devolver un dict, list, valores singulares como str, int, etc.
También puedes devolver modelos de Pydantic (verás más sobre eso después).
Hay muchos otros objetos y modelos que serán convertidos automáticamente a JSON (incluyendo ORMs, etc). Prueba usar tus favoritos, es muy probable que ya estén soportados.
Paso 6: Desplegarlo¶
Despliega tu app a FastAPI Cloud con un comando: fastapi deploy. 🎉
Acerca de FastAPI Cloud¶
FastAPI Cloud es construido por el mismo autor y equipo detrás de FastAPI.
Simplifica el proceso de construir, desplegar y acceder a una API con mínimo esfuerzo.
Trae la misma experiencia de desarrollador de construir apps con FastAPI a desplegarlas en la nube. 🎉
FastAPI Cloud es el principal patrocinador y proveedor de financiación para los proyectos open source de FastAPI and friends. ✨
Desplegar en otros proveedores de nube¶
FastAPI es de código abierto y está basado en estándares. Puedes desplegar aplicaciones FastAPI en cualquier proveedor de nube que elijas.
Sigue las guías de tu proveedor de nube para desplegar aplicaciones FastAPI con ellos. 🤓
Resumen¶
- Importa
FastAPI. - Crea una instancia
app. - Escribe un path operation decorator usando decorators como
@app.get("/"). - Define una path operation function; por ejemplo,
def root(): .... - Ejecuta el servidor de desarrollo usando el comando
fastapi dev. - Opcionalmente despliega tu app con
fastapi deploy.