Saltar a contenido

API Overview

Convenciones generales

  • Base path: Todas las rutas expuestas por FastAPI se montan bajo /api (app/main.py).
  • Autenticación:
  • Cookie session_token (emitida en login) o header Authorization: Bearer <token>.
  • Usa app/auth/auth_dependencies.get_current_user; si el token no es válido devuelve HTTP 401 con {"detail": "No se pudo validar el usuario"}.
  • Permisos:
  • Cada endpoint incluye una dependencia Access*.XXX.requiere. Si el usuario no posee el permiso retorna HTTP 403 "No disponible".
  • Los dominios disponibles: admin, ingenieria, construccion, lda. El superusuario trae automáticamente ('*', '*').
  • Sesión de base de datos:
  • SessionDep (app/core/database.py) inyecta una sesión SQLModel/SQLAlchemy por solicitud.

Paginación y filtros

Los listados siguen el contrato PageModel (app/models/responses.py):

  • Query params estándar: page, size, search, order_by, ascending.
  • La respuesta incluye total (conteo total) y data (lista tipada por recurso).
  • search acepta:
  • Texto libre (modo simple) sobre columnas marcadas como simple=True.
  • DSL avanzado según app/utils/search_dsl.py (operadores ~=, ^=, =, !=, >, >=, <, <=, rangos v1..v2, listas in [...], negaciones -campo=..., OR con |, etc.).
  • El frontend DynamicTable genera estas expresiones automáticamente.

Helpers disponibles en las rutas (ver app/utils/listing.py):

  • auto_specs_from_model para derivar ColumnSpec desde el modelo SQLAlchemy.
  • dsl(search, *specs) para construir condiciones where.
  • order_map_from_model y resolve_order para traducir alias a columnas y aplicar asc/desc.
  • paginate(session, base, page, order) para ejecutar el query paginado con COUNT.

Dependencias comunes

Dependencia Descripción
current_user: CurrentUser Usuario autenticado (UsuarioBase) con permisos y menús.
centros_costos: centroCostosDep Lista de IDs de centros de costos válidos para el usuario (deriva de la cookie cfg:centros_costos). Las rutas que operan sobre proyectos/ingeniería/construcción la usan como filtro obligatorio.
redis_client Cliente global Redis (app/core/redis.py), utilizado en logs, sesiones y scheduler.

Manejo de errores

  • La mayoría de los endpoints usan HTTPException con mensajes simples y códigos apropiados (400, 401, 403, 404, 409, 500).
  • Operaciones largas (backups) se envuelven en stream_executor, por lo que el cliente recibe un stream JSON aunque el proceso tarde minutos.
  • Validaciones raras (por ejemplo, DSL inválido) retornan {"detail": "Filtro inválido: ..."} con código 400.

Versionado y documentación

  • Swagger UI en /api/docs.
  • OpenAPI en /api/openapi.json.
  • Redoc en /api/redoc.

Documentos complementarios