Template API REST FastAPI

Template de un servicio API Rest desarrollado en Python con el framework FastAPI, Pydantic, SQLAlchemy, PostgreSQL, Pytest y Docker. El template cubre la de gestión de usuarios y usa tokens jwt para autenticación.

Indice

• Tecnología
• Requisitos
• Configuración
  • Variables de entorno
• Instalar dependencias
• Documentación (OpenAPI)
• Comandos Makefile
  • Comandos ejecución entorno PRO
  • Comandos ejecución entorno DEV
  • Comandos ejecución tests
• Endpoints
  • Users
  • Auth
• CI-CD
  • CI (Continuous Integration)
• Ejemplo de expansion de este template

Tecnología

• Web Framework: FastAPI
• ORM: SQLAlchemy
• Autenticación: PyJWT (JSON Web Token)
• Serialización, Deserialización y Validación: Pydantic
• Documentación: Swagger-UI
• Authentication: PyJWT
• Tests: Pytest
• Cobertura de código: Pytest-cov
• Base De Datos: PostgreSQL y SQLite
• Gestor de dependencias/environments: UV
• Linter/Formatter: Ruff
• Contenirizacion: Docker y docker-compose
• CI/CD: Github Actions

Requisitos

• UV
• Docker
• Docker-Compose
• Python 3.12
• Github
• Makefile

Configuración

Variables de entorno

# Las opciones de PROJECT_ENV son PRO y TEST
PROJECT_ENV

# Datos del primer usuario con rol admin
ADMIN_USER_USERNAME
ADMIN_USER_EMAIL
ADMIN_USER_PASSWORD

# Datos de configuracion de POSTGRES
POSTGRES_SERVER # Host desde el equipo local
POSTGRES_PORT
POSTGRES_USER
POSTGRES_PASSWORD
POSTGRES_DB

# Secret key para JWT
JWT_SECRET_KEY

Instalar dependencias

make install-dependencias

o

uv sync --all-extras --dev
source .venv/bin/activate

Documentación (OpenAPI)

La visualización de la documentación de OpenAPI por defecto es en localhost:8000/docs.

Comandos Makefile

Comandos ejecución entorno PRO

• Levantar el entorno pro.

  make pro-up

• Suspender el entorno pro.

  make pro-down

• Suspender el entorno pro y eliminar los volumenes docker.

  make pro-down-remove-data

• Suspender el entorno pro y eliminar los volumenes e imagenes de docker.

  make pro-down-remove-all

• Visualizar los logs del entorno pro.

  make pro-logs

Comandos ejecución entorno DEV

• Levantar el entorno dev.

  make dev-up

• Suspender el entorno dev.

  make dev-down

• Suspender el entorno dev y eliminar los volumenes docker.

  make dev-down-remove-data

• Suspender el entorno dev y eliminar los volumenes e imagenes de docker.

  make dev-down-remove-all

• Visualizar los logs del entorno dev.

  make dev-logs

Comandos ejecución tests

• Ejecutar tests sin coverage:

  make tests

• Ejecutar tests repository sin coverage:

  make tests-repository

• Ejecutar tests api sin coverage:

  make tests-api

• Ejecutar tests con coverage sin reporte en html:

  make tests-cov

• Ejecutar tests con coverage con reporte en html:

  make tests-cov-html

NOTA: La API Rest usa por defecto el host localhost y el puerto 8000.

Endpoints

Roles: user, admin

Users

Endpoint	HTTP Method	Result	Role
/users	POST	Crear nuevo usuario	user, admin
/users	GET	Obtener todos los usuarios	admin
/users/{username}	GET	Obtener un usuario por username	admin
/users/{username}	PUT	Actualizar un usuario por username	admin
/users/{username}	DELETE	Eliminar un usuario por username	admin
/users/me	GET	Obtener el usuario actual	user, admin
/users/me	PUT	Actualizar el usuario actual	user, admin
/users/me	DELETE	Eliminar el usuario actual	user, admin

La implementación de los endpoints de user esta en app/api/v1/routers/users/users_routers.py.

Auth

Endpoint	HTTP Method	Result	Role
/auth/login	POST	Login de un usuario	user, admin

La implementación de los endpoints de auth esta en app/api/v1/routers/auth/auth_routers.py.

CI-CD

CI (Continuous Integration)

El workflow de CI (ci.yml) utiliza Github Actions, como el Github Action setup-uv para utilizar comandos de uv, más información aquí. El workflow ejecuta los tests de API y los test de repositoris cuando se realiza un pull-request a main y develop o un push a develop.

Ejemplo de expansion de este template

Necesitas añadir items que permita a los usuarios hacer CRUD en sus artículos:

1. Crear un modelo de base de datos item en app/database/models.
2. Crear un directorio item en el directorio app/api/v1/routers
   1. Crear schemas de item para load, dump y validación en app/api/v1/routers/item/item_schemas.py.
   2. Crear funciones repository de item en app/api/v1/routers/item/item_repository.py.
   3. Crear funciones endpoint de item en app/api/v1/routers/item/item_routers.py.
3. Añadir el APIRouter de items en app/api/v1/main.py
4. Crea nuevos tests para el nuevo módulo:
   1. Crear el directorio de tests de api en el directorio tests/api/routes (convención para este proyecto) y crear ficheros por cada función a testear para escribir los tests.
   2. Crear el directorio de tests de repository en el directorio tests/repository (convención para este proyecto) y crear ficheros por cada función a testear para escribir los tests.
   3. Crear fichero de funciones utiles para item en el directorio tests/utils (convención para este proyecto).
   4. Crear peticiones en postman (Opcional).
5. Añadir los endpoints en README

Aviso de descargo de responsabilidad

En ningún caso me hago responsable por daños y perjuicios, incluidos, entre otros, daños y perjuicios indirectos o de carácter secundario, o daños y perjuicios por pérdidas o beneficios derivados de, o relacionados con, la utilización de este software.

Tú, como usuario, actúas por tu cuenta y riesgo si decides utilizar este software.

Contribución

Siéntete libre de realizar cualquier sugerencia o mejora al proyecto.