Lección 46 de 47 · Proyecto final: CRUD de tareas con SQLite✦ WebMCP implementado
Fase 5: la API con FastAPI y uvicorn
10 min de lectura4 retos
Hasta aquí todo funciona, pero solo desde Python. Ahora le das una puerta a la calle: una API HTTP con FastAPI que reparte las peticiones a tus casos de uso, y uvicorn, el servidor que la pone en marcha. Es el public/index.php y el nginx + php-fpm del proyecto, en dos piezas.
¿De dónde vienen los nombres?
FastAPI = inglés fast (rápido) + API
El framework web del proyecto. Reparte las peticiones a tus funciones, valida los datos y genera la documentación sola.
ASGI = inglés Asynchronous Server Gateway Interface (interfaz de pasarela de servidor asíncrona)
El contrato entre un servidor (uvicorn) y una app (FastAPI): una función async que recibe scope, receive y send. Es el FastCGI de PHP, para Python.
Depends = inglés depends (depende de)
La marca que dice «esta ruta depende de este objeto»: FastAPI lo construye y se lo pasa. Es el contenedor de dependencias de la ruta.
HTTPException = HTTP = HyperText Transfer Protocol (protocolo de transferencia de hipertexto) + exception (excepción)
Una excepción que FastAPI convierte en una respuesta de error con el código que le indiques (404, 422…).
lifespan = inglés life span (duración de la vida)
El ciclo de vida de la app: lo que se ejecuta una vez al arrancar y otra al apagar. Es el sitio para migrar la base de datos.
En 4 ideas
1/4
FastAPI te da lo que PHP traía de serie: rutas (@app.get("/tareas")), la lectura de la petición y la respuesta en JSON. Los type hints de la función (id: int) hacen de validación: /tareas/abc devuelve un 422 sin escribir un if.
FastAPI no es un servidor: es una app ASGI. Necesita uvicorn (uvicorn app.main:app) que escucha en el puerto y la llama por cada petición. En PHP, nginx + php-fpm hacían ese trabajo; en Python lo pones tú. Más detalle en FastAPI y por qué necesita uvicorn.
Los datos que entran y salen son modelos pydantic (TareaNueva, TareaSalida), y cada ruta pide su caso de uso con Depends(...). La ruta no construye nada: es el DTO + el controlador de PHP, con inyección hecha por el framework.
El dominio lanza TareaNoEncontrada; la ruta la traduce con HTTPException(404). Cada resultado lleva su código: 201 crear, 200 leer, 204 borrar sin cuerpo, 404 no existe, 422 datos inválidos. Nunca un 200 con un error dentro.
1 · Qué hace un framework web (lo que PHP te regalaba)
En la lección Python no nació para la web viste que Python no trae $_GET, ni rutas, ni servidor. Un framework web es el que pone esas piezas. Antes de usar FastAPI, mira lo que hace por dentro con un juguete de 25 líneas que sí corre aquí: un registro de rutas con un decorador (módulo 07) y un buscador que casa el camino con la función.
Pythonmain.py
import re
RUTAS = []
defruta(metodo, patron):
"""Registra una función para un método y un camino como /tareas/{id}."""
regex = re.compile("^" + re.sub(r"\{(\w+)\}", r"(?P<\1>[^/]+)", patron) + "$")
defregistrar(funcion):
RUTAS.append((metodo, regex, funcion))
return funcion
return registrar
@ruta("GET", "/tareas/{id}")
defver_tarea(id):
return {"id": int(id), "titulo": "Comprar pan"}
@ruta("GET", "/salud")
defsalud():
return {"estado": "ok"}
defatender(metodo, camino):
for metodo_ruta, regex, funcion inRUTAS:
coincidencia = regex.match(camino)
if metodo_ruta == metodo and coincidencia:
return200, funcion(**coincidencia.groupdict())
return404, {"detail": "Not Found"}
print(atender("GET", "/salud"))
print(atender("GET", "/tareas/7"))
print(atender("GET", "/nada"))
Eso es, en miniatura, lo que hace un framework: guardar una lista de «si llega este método y este camino, llama a esta función», sacar los trozos del camino ({id}) y pasárselos como argumentos. FastAPI hace lo mismo y además convierte y valida los tipos y escribe la respuesta en JSON. Lo mismo, con el servidor de pruebas incluido:
PHP 8.5index.php
<?phpdeclare(strict_types=1);
// public/index.php: sin framework, el «router» es un match$metodo = $_SERVER["REQUEST_METHOD"];
$camino = parse_url($_SERVER["REQUEST_URI"], PHP_URL_PATH);
[$codigo, $cuerpo] = match (true) {
$metodo === "GET" && $camino === "/salud" => [200, ["estado" => "ok"]],
default => [404, ["detail" => "Not Found"]],
};
http_response_code($codigo);
header("Content-Type: application/json");
echojson_encode($cuerpo);
Pythonmain.pySolo lectura: necesita FastAPI y un servidor
@app.get("/salud") es el decorador de rutas (el ruta(...) de nuestro juguete): une método + camino con la función de debajo.
La función devuelve un diccionario y FastAPI lo convierte en JSON con el Content-Type correcto: no hay json_encode ni header().
Un camino que no existe da 404 y un método no permitido en un camino que sí existe (POST /salud) da 405, solos. En index.php habría que escribir cada caso.
TestClient llama a la app sin abrir ningún puerto: es el cliente de pruebas. Lo usaremos en la fase 6.
¿Por qué? · En PHP no existe
¿Por qué los tipos de la función (id: int) validan la petición? En PHP habría que escribir el if
En PHP, $_GET['id'] llega siempre como texto: tú haces (int) y rezas, o escribes un filter_var y un if. Con /tareas/abc el (int) da 0 sin protestar, y buscas la tarea 0.
FastAPI lee los type hints de tu función (módulo 01) y los usa como contrato: si declaras id: int, convierte "7" en 7 y, si llega "abc", responde 422sin llamar a tu función. Es lo mismo que haría un declare(strict_types=1) aplicado a la URL. Los mismos tipos que escribes para documentar, validan.
2 · Por qué FastAPI necesita uvicorn
Mira lo que has ejecutado arriba: TestClient llama a la app directamente, sin red. Pero para atender a un navegador alguien tiene que abrir un puerto, leer los bytes HTTP, convertirlos en algo que tu código entienda y escribir la respuesta. En PHP, nginx habla HTTP y php-fpm ejecuta tu script. FastAPI no hace ninguna de las dos cosas: es solo la app.
Ese «algo que tu código entiende» es ASGI: una app es una función async que recibe scope (qué se pide), receive (para leer el cuerpo) y send (para contestar). Aquí tienes una app ASGI entera y un servidor de juguete que la llama, como haría uvicorn por cada petición:
Pythonmain.py
import asyncio
asyncdefapp(scope, receive, send):
"""Una aplicación ASGI mínima: lo que FastAPI es por dentro."""
cuerpo = f"Hola desde {scope['method']} {scope['path']}".encode()
awaitsend({"type": "http.response.start", "status": 200, "headers": [(b"content-type", b"text/plain")]})
awaitsend({"type": "http.response.body", "body": cuerpo})
asyncdefservidor_de_juguete():
"""Lo que uvicorn hace por cada petición: montar el scope y llamar a la app."""
mensajes = []
asyncdefreceive():
return {"type": "http.request", "body": b""}
asyncdefsend(mensaje):
mensajes.append(mensaje)
awaitapp({"type": "http", "method": "GET", "path": "/tareas"}, receive, send)
for mensaje in mensajes:
print(mensaje)
asyncio.run(servidor_de_juguete())
#
Pieza
En PHP
En Python
1
Escucha el puerto 80/443 y habla HTTP con el mundo
nginx
nginx (delante) y uvicorn
2
Arranca tu código por cada petición
php-fpm ejecuta index.php de cero cada vez
uvicorn llama a la app, que ya está cargada en memoria
3
El contrato entre servidor y código
FastCGI
ASGI
4
Rutas, validación y JSON
Laravel, Symfony o index.php a mano
FastAPI
¿Por qué? · En PHP no existe
¿Por qué uvicorn y no «ejecutar el fichero con python»? En PHP, php -S lo hacía todo
php -S es un servidor de desarrollo dentro del propio PHP. Python no trae un servidor listo para una app moderna: el módulo http.server es muy básico. Y FastAPI es async (módulo 08): necesita un servidor que sepa manejar un bucle de eventos y muchas conexiones abiertas a la vez, que es justo lo que hace uvicorn.
La diferencia clave con PHP: aquí el proceso vive. En php-fpm cada petición empieza de cero; en uvicorn tu app se carga una vez y atiende miles de peticiones. Ventaja: no vuelves a conectar ni a cargar todo cada vez. Coste: lo que guardes en una variable global se comparte entre peticiones, y un error de memoria se queda. Por eso cada petición abre y cierra su propia conexión a la base de datos (siguiente sección).
3 · Los datos de entrada y de salida: modelos pydantic
Cuando alguien hace POST /tareas con un JSON, hay que comprobar que trae un título, que la prioridad es un número válido… En PHP escribirías un DTO y varios if. En FastAPI describes la forma con una clase que hereda de BaseModel (de pydantic), y la validación sale sola:
$ python main.py
titulo='Comprar pan' prioridad=<Prioridad.MEDIA: 1> etiquetas=[]
titulo='Llamar' prioridad=<Prioridad.ALTA: 2> etiquetas=[]
('titulo',) -> String should have at least 1 character
('prioridad',) -> Input should be 0, 1 or 2
TareaNueva es un modelo: una clase con campos tipados, parecida a un @dataclass, pero que valida al crearse.
Field(min_length=1, max_length=200) pone los límites del título. Prioridad se usa como tipo: pydantic comprueba que sea 0, 1 o 2.
Fíjate en la segunda línea: "prioridad": "2" (texto) se convierte en Prioridad.ALTA. Pydantic convierte lo que puede y rechaza lo que no.
Si falla, lanza ValidationError con la lista de fallos (qué campo y por qué). FastAPI la convierte sola en una respuesta 422.
Y hay un segundo modelo para lo que sale, TareaSalida: así la respuesta contiene solo los campos que decides (nunca un dato interno por descuido), y se documenta sola. El fichero del proyecto, app/infrastructure/api/esquemas.py:
Un modelo pydantic hace de DTO, de validador y de serializador a la vez.
PHP
Python
Quién lo ve
Un DTO final readonly class TareaNueva
class TareaNueva(BaseModel)
La API (capa de infraestructura): el dominio no lo conoce
Los if o un Validator de Symfony
Field(min_length=1) y los type hints
Los hace pydantic al crear el objeto
readonly / JsonSerializable
model_dump() y from_attributes=True
Convierte a diccionario o lee de la Tarea del dominio
Un enum como tipo de campo
prioridad: Prioridad
Acepta 0, 1, 2 y rechaza el resto
¿Por qué? · En PHP no existe
¿Por qué dos modelos (TareaNueva y TareaSalida) y no usar la Tarea del dominio directamente?
Porque entrada y salida no son lo mismo. Al crear no mandas id ni hecha (los pone la app); al devolver sí. Si usaras una sola clase, el cliente podría mandar su propio id o marcar la tarea como hecha desde el principio.
Y porque así la API puede cambiar sin tocar el dominio: mañana puedes renombrar un campo del JSON sin cambiar la Tarea. Es el motivo de las capas: el dominio no sabe que existe HTTP, ni pydantic.
4 · Depends: la ruta pide lo que necesita
Cada ruta necesita su caso de uso, y cada caso de uso su repositorio, y el repositorio una conexión a SQLite. Quién construye todo eso. En FastAPI lo hace Depends: tú escribes una función que sabe fabricar la pieza, y la ruta la pide poniéndola como parámetro. Es la raíz de composición de la fase 4, pero con el framework haciendo de contenedor. Mira el mecanismo en pequeño:
Pythonmain.pySolo lectura: necesita FastAPI
from fastapi importDepends, FastAPI, HTTPExceptionfrom fastapi.testclient importTestClientTAREAS = {1: "Comprar pan"}
classRepositorioReal:
deftitulo(self, id):
returnTAREAS.get(id)
classRepositorioFalso:
deftitulo(self, id):
return"titulo de pruebas"defget_repositorio():
returnRepositorioReal()
app = FastAPI()
@app.get("/tareas/{id}")
defver(id: int, repositorio=Depends(get_repositorio)):
titulo = repositorio.titulo(id)
if titulo isNone:
raiseHTTPException(status_code=404, detail=f"No existe la tarea {id}")
return {"id": id, "titulo": titulo}
cliente = TestClient(app)
print(cliente.get("/tareas/1").json())
print(cliente.get("/tareas/7").status_code, cliente.get("/tareas/7").json())
print(cliente.get("/tareas/abc").status_code)
app.dependency_overrides[get_repositorio] = RepositorioFalsoprint(cliente.get("/tareas/7").json())
$ python main.py
{'id': 1, 'titulo': 'Comprar pan'}
404 {'detail': 'No existe la tarea 7'}
422
{'id': 7, 'titulo': 'titulo de pruebas'}
repositorio=Depends(get_repositorio) dice: «antes de llamarme, llama a get_repositorio() y pásame lo que devuelva».
La ruta no sabe si recibe el repositorio real o uno falso. Solo sabe que tiene titulo().
app.dependency_overrides[...]sustituye la pieza en los tests: la última línea hace que la tarea 7 «exista» sin tocar la ruta. Es el bind() de un contenedor de PHP en un test.
/tareas/abc da 422 antes de llegar a la función: el id: int hizo de validador.
En el proyecto real, la dependencia de abajo es la conexión a SQLite. app/infrastructure/api/dependencias.py la abre, la entrega y la cierra al terminar la petición, gracias a yield:
¿Por qué yield y una conexión nueva por petición? En PHP el script moría y la conexión con él
En PHP, cuando acababa la petición, el proceso soltaba todo. En uvicorn el proceso sigue vivo, así que si abres una conexión y no la cierras, se acumulan. Con yield, FastAPI ejecuta lo que hay antes del yield para fabricar la pieza, y lo que hay después (el finally) al terminar la petición, pase lo que pase. Es un gestor de contexto (with, módulo 07) para toda la ruta.
¿Y por qué no una única conexión global, como un static de PHP? Porque dos peticiones simultáneas la usarían a la vez, y SQLite no admite que dos hilos escriban por la misma conexión sin cuidado. Con una conexión por petición, cada una va por su lado.
5 · De errores del dominio a códigos HTTP
El dominio lanza TareaNoEncontrada, pero un navegador no entiende de excepciones de Python: entiende códigos de estado. Quien traduce es la capa de la API, y no el dominio. Cada resultado tiene su código:
#
Código
Cuándo
Ejemplo del proyecto
1
200 OK
Va bien y hay cuerpo
GET /tareas, POST /tareas/1/completar
2
201 Created
Se ha creado algo
POST /tareas
3
204 No Content
Va bien y no hay cuerpo
DELETE /tareas/1
4
404 Not Found
Lo que pides no existe
TareaNoEncontrada
5
422 Unprocessable Content
Los datos no valen
Título vacío, prioridad 7
6
500 Internal Server Error
Un fallo tuyo que no esperabas
Una excepción sin atrapar
La traducción es una tabla de «este error → este código». Aquí la tienes como lógica pura, que sí corre en el navegador:
Pythonmain.py
from http importHTTPStatusclassDominioError(Exception):
passclassTituloVacio(DominioError):
passclassTareaNoEncontrada(DominioError):
def__init__(self, id):
super().__init__(f"No existe la tarea {id}")
self.id = id
defcodigo_http(error):
# En PHP: match (true) { $e instanceof TareaNoEncontrada => 404, ... }ifisinstance(error, TareaNoEncontrada):
returnHTTPStatus.NOT_FOUNDifisinstance(error, TituloVacio):
returnHTTPStatus.UNPROCESSABLE_CONTENTreturnHTTPStatus.INTERNAL_SERVER_ERRORfor error in [TareaNoEncontrada(7), TituloVacio("vacío"), ValueError("raro")]:
estado = codigo_http(error)
print(f"{type(error).__name__}: {estado.value} {estado.phrase}")
En FastAPI, esa traducción es un try / except que lanza HTTPException: una excepción especial que el framework convierte en la respuesta de error. Así quedan las rutas del proyecto, app/infrastructure/api/rutas.py:
Las rutas usan el try/except y el raise ... from del módulo 07.
PHP
Python
Quién lo ve
try { ... } catch (TareaNoEncontrada $e) { ... }
try: ... except TareaNoEncontrada as error: ...
Solo ese bloque
throw new HttpException(404, ..., previous: $e)
raise HTTPException(404, ...) from error
FastAPI: lo convierte en la respuesta
#[Route('/tareas', methods: ['POST'])]
@router.post("") con prefix="/tareas"
El registro de rutas de FastAPI
new Response(status: 201)
status_code=status.HTTP_201_CREATED
El código de la respuesta si todo va bien
¿Por qué? · En PHP no existe
¿Por qué from error en el raise? ¿Y por qué no devolver {"error": ...} con un 200?
raise ... from error guarda la causa original (como el previous de las excepciones de PHP). Si más tarde miras el log, ves que el 404 nació de una TareaNoEncontrada, y no solo un 404 sin historia.
Y devolver un 200 con {"error": "no existe"} es un fallo clásico: el cliente, un navegador o un curl --fail, ve éxito. Los monitores, las cachés y los reintentos se guían por el código. El 200 con error dentro es de los fallos más difíciles de detectar, porque nada se rompe a la vista.
6 · Arrancar con uvicorn y probar la API
La última pieza es app/main.py, que crea la aplicación, enchufa las rutas y migra la base de datos al arrancar (una sola vez, no en cada petición). Usa un lifespan: una función con yield que FastAPI ejecuta al empezar (antes del yield) y al terminar (después):
Pythonmain.py
import sqlite3
from contextlib import asynccontextmanager
from fastapi importFastAPIfrom app.infrastructure.api.dependencias import ruta_bd
from app.infrastructure.api.rutas import router
from app.infrastructure.sqlite.migraciones import migrar
@asynccontextmanagerasyncdefciclo_de_vida(app: FastAPI):
conexion = sqlite3.connect(ruta_bd())
migrar(conexion)
conexion.close()
yield
app = FastAPI(title="Tareas", version="1.0.0", lifespan=ciclo_de_vida)
app.include_router(router)
Y ahora, a arrancarla. El comando es siempre el mismo: uvicorn <módulo>:<variable>. Aquí, el módulo app.main y la variable app:
app.main:app se lee «el fichero app/main.py, la variable app». Los dos puntos separan el módulo del objeto.
--reload reinicia el servidor al guardar un fichero. En PHP no lo necesitabas, porque cada petición leía los ficheros de nuevo; aquí el proceso vive y hay que reiniciarlo. Solo para desarrollo.
FastAPI genera sola la documentación interactiva en http://localhost:8000/docs (Swagger) y el esquema en /openapi.json: pruebas la API desde el navegador sin escribir un curl.
Para probarla sin abrir ningún puerto, usa TestClient: es lo que hará la fase 6. Este pequeño script llama a las rutas reales del proyecto y las salidas que ves son las que da:
Crear una tarea devuelve 201 Created. Usa http.HTTPStatus para que el programa imprima exactamente 201 Created (el número y su texto). Es el http_response_code(201) de PHP.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista.HTTPStatus es un enum con todos los códigos: HTTPStatus.CREATED vale 201, y cada miembro tiene .value y .phrase.
Reto 2 de 4 · ✓ Resuelto
Del error al código
Escribe codigo_http(error): 404 si el error es TareaNoEncontrada, 422 si es TituloVacio, 400 para cualquier otro DominioError y 500 para cualquier otra excepción. Devuelve un int normal. Es el match con instanceof de PHP.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Usa isinstance(error, Clase). El orden importa: pregunta primero por las clases concretas (TareaNoEncontrada, TituloVacio) y después por el padre DominioError, o el padre se las comería.
Reto 3 de 4 · ✓ Resuelto
Validar lo que entra
Escribe validar_tarea_nueva(datos): recibe el diccionario del JSON y devuelve la lista de errores (vacía si todo va bien), en este orden: titulo: obligatorio si falta la clave, titulo: debe ser texto si no es un str, titulo: no puede estar vacío si queda vacío tras strip(), titulo: máximo 200 caracteres si pasa de 200; y prioridad: debe ser 0, 1 o 2 si la clave prioridad existe y no es un int entre 0 y 2 (un bool no vale). Es el trabajo que hace pydantic por ti.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Encadena if / elif para el título (solo se cuenta un fallo por campo) y un if aparte para la prioridad. Cuidado: True es un int en Python (isinstance(True, int) es True), así que hay que descartar los bool antes.
Reto 4 de 4 · ✓ Resuelto
La respuesta de una acción
Escribe responder(accion, exito=200): llama a accion() y devuelve una tupla (código, cuerpo). Si va bien, (exito, resultado); con exito=204 el cuerpo es siempre None. Si lanza un error del dominio, (codigo_http(error), {"detail": str(error)}). Cualquier otra excepción no se atrapa: sube. Es el try/catch de un controlador de PHP.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Envuelve solo accion() en un try y atrapa soloDominioError: así un ValueError sube solo. Después de la llamada, si exito == 204 devuelve None como cuerpo.
Resumen
Lo que te llevas de esta lección
FastAPI es la app (rutas, validación, JSON) y uvicorn el servidor: uvicorn app.main:app (en PHP, index.php y nginx + php-fpm).
Los type hints validan la petición: id: int da un 422 si llega abc, sin un solo if (en PHP, (int) y un filter_var).
Entrada y salida son modelos pydantic distintos (TareaNueva, TareaSalida): el dominio no sabe que existen (en PHP, los DTO).
Depends construye lo que la ruta necesita, y con yield cierra la conexión al acabar la petición (en PHP, el contenedor de dependencias).
El dominio lanza errores y la API los traduce con HTTPException(404): nunca un 200 con un error dentro.
Para recordarlo: «Ruta, Modelo, Depende, Estado»
RRuta @router.post("")
MModelo TareaNueva y TareaSalida
DDepende Depends(get_crear)
EEstado HTTP HTTPException(404)
Toda ruta de la API lleva cuatro cosas: su Ruta, el Modelo de lo que entra y sale, lo que Depende (Depends) y el Estado HTTP que devuelve en cada caso.