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 en un archivo main.py.
Ejecuta el servidor en vivo:
En el resultado, 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 aplicación está siendo servida, en tu máquina local.
Compruébalo¶
Abre tu navegador en http://127.0.0.1:8000.
Verás el response 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 "esquema" con toda tu API utilizando el estándar OpenAPI para definir APIs.
"Esquema"¶
Un "esquema" es una definición o descripción de algo. No el código que lo implementa, sino solo una descripción abstracta.
Esquema de la API¶
En este caso, OpenAPI es una especificación que dicta cómo definir un esquema de tu API.
Esta definición de esquema incluye los paths de tu API, los posibles parámetros que toman, etc.
Esquema de Datos¶
El término "esquema" también podría referirse a la forma de algunos datos, como el contenido JSON.
En ese caso, significaría los atributos del JSON, los tipos de datos que tienen, etc.
OpenAPI y JSON Schema¶
OpenAPI define un esquema de API para tu API. Y ese esquema incluye definiciones (o "esquemas") de los datos enviados y recibidos por tu API utilizando JSON Schema, el estándar para esquemas de datos JSON.
Revisa el openapi.json¶
Si tienes curiosidad por cómo se ve el esquema OpenAPI en bruto, FastAPI automáticamente genera un JSON (esquema) con las descripciones de toda tu API.
Puedes verlo directamente en: http://127.0.0.1:8000/openapi.json.
Mostrará un JSON que empieza 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 esquema 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 comuniquen con tu API. Por ejemplo, aplicaciones frontend, móviles o IoT.
Recapitulación, paso a paso¶
Paso 1: importa 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: crea una "instance" de FastAPI¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Aquí la variable app será una "instance" de la clase FastAPI.
Este será el punto principal de interacción para crear toda tu API.
Paso 3: crea una path operation¶
Path¶
"Path" aquí se refiere a la última parte de la URL empezando desde la primera /.
Así que, en una URL como:
https://example.com/items/foo
...el path sería:
/items/foo
Info
Un "path" también es comúnmente llamado "endpoint" o "ruta".
Mientras construyes una API, el "path" es la forma principal de separar "concerns" y "resources".
Operación¶
"Operación" aquí se refiere a uno de los "métodos" HTTP.
Uno de:
POSTGETPUTDELETE
...y los más exóticos:
OPTIONSHEADPATCHTRACE
En el protocolo HTTP, puedes comunicarte con cada path usando uno (o más) de estos "métodos".
Al construir APIs, normalmente usas estos métodos 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í que, en OpenAPI, cada uno de los métodos HTTP se llama una "operation".
Vamos a llamarlas "operaciones" también.
Define 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 requests que vayan a:
- el path
/ - usando una
getoperation
Información sobre @decorator
Esa sintaxis @algo en Python se llama un "decorador".
Lo pones encima de una función. Como un bonito sombrero decorativo (supongo que de ahí viene el término).
Un "decorador" toma la función de abajo y hace algo con ella.
En nuestro caso, este decorador 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 operaciones:
@app.post()@app.put()@app.delete()
Y los más exóticos:
@app.options()@app.head()@app.patch()@app.trace()
Tip
Eres libre de usar cada operación (método HTTP) como quieras.
FastAPI no fuerza ningún significado específico.
La información aquí se presenta como una guía, no un requisito.
Por ejemplo, cuando usas GraphQL normalmente realizas todas las acciones usando solo operaciones POST.
Paso 4: define la path operation function¶
Esta es nuestra "path operation function":
- path: es
/. - operation: es
get. - function: es la función debajo del "decorador" (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 cuando reciba un request en la URL "/" usando una operación 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 sabes la diferencia, revisa la sección Async: "¿Tienes prisa?".
Paso 5: retorna el contenido¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Puedes retornar un dict, list, valores singulares como str, int, etc.
También puedes retornar modelos de Pydantic (verás más sobre eso más adelante).
Hay muchos otros objetos y modelos que serán automáticamente convertidos a JSON (incluyendo ORMs, etc). Intenta usar tus favoritos, es altamente probable que ya sean compatibles.
Recapitulación¶
- Importa
FastAPI. - Crea una instancia
app. - Escribe un path operation decorator usando decoradores como
@app.get("/"). - Define una path operation function; por ejemplo,
def root(): .... - Ejecuta el servidor de desarrollo usando el comando
fastapi dev.