Plantilla de API en Python

Plantilla mínima y reutilizable para una API REST construida con FastAPI. Incluye un único endpoint GET /ping para verificar que la aplicación está funcionando.

Requisitos

• uv
• Docker para el modo contenedor

uv administra Python 3.14 y las dependencias del proyecto. Las versiones exactas de las dependencias quedan registradas en uv.lock.

Configuración inicial

uv sync
uv run pre-commit install --install-hooks

El segundo comando instala dos hooks de Git: pre-commit ejecuta todas las pruebas dentro de tests/, mientras que commit-msg rechaza los mensajes que no siguen Conventional Commits:

tipo(alcance-opcional): descripción

Por ejemplo: feat: agregar endpoint de usuarios.

Ejecución

En modo local, con sincronización de dependencias y recarga automática:

./start-api local

./start-api utiliza el modo local de forma predeterminada. Para construir y ejecutar la API en un contenedor Docker descartable:

./start-api docker

La API queda disponible en http://127.0.0.1:8000. La documentación interactiva está disponible en /docs y /redoc.

Ping

curl http://127.0.0.1:8000/ping

Respuesta:

{"message":"pong"}

Pruebas

uv run pytest

El ejemplo en tests/test_ping.py envía una petición a la aplicación y comprueba el código de estado y el cuerpo de la respuesta.

Estructura

app/
├── main.py
└── routes/
    └── ping.py
tests/
├── test_ping.py
└── test_start_api.py
Dockerfile
start-api

main.py crea la aplicación y registra los routers. Las definiciones de los endpoints se encuentran en app/routes, permitiendo agregar nuevos dominios sin hacer crecer el punto de entrada.

Próximas incorporaciones

La integración con una base de datos y una capa de configuración de la aplicación se omiten intencionalmente. Deben agregarse cuando un proyecto tenga requisitos concretos para ellas.