0009. Prefijo de versión de la API en cada router¶
Estado: Propuesto Fecha: 2026-09-29 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/domains/*/router.py, app/main.py
Contexto¶
El ADR 0016 transversal versiona la API en el path (/api/v1/...) y sube la
versión por contrato: si un dominio rompe su contrato nace /api/v2/...
para ese dominio, mientras los demás siguen en v1. El servicio ponía el
prefijo en un solo lugar, app/main.py (include_router(router,
prefix=PREFIJO_API)), mientras core-svc-template y core-svc-identidad lo
declaran en cada router. En la revisión se pidió alinearlo.
Decisión¶
- Cada router declara su ruta completa con la versión:
APIRouter(prefix="/api/v1/catalogos", tags=["catalogos"]). app/main.pymonta los routers sinprefix(application.include_router(catalogos_router)); se elimina la constantePREFIJO_API.- Si un dominio necesita una versión nueva, la declara en su propio router
(
/api/v2/<dominio>) sin tocarmain.pyni los demás dominios.
Alternativas descartadas¶
- Prefijo único en
app/main.py(lo que había) — es el ejemplo que muestra el ADR 0016 transversal, pero la versión queda lejos de los endpoints y una constante global no representa bien versiones distintas por dominio. - Prefijo mixto (
/api/v1enmain.pyy/catalogosen el router) — obliga a leer dos archivos para saber la URL real de un endpoint.
Consecuencias¶
- La URL completa de cada endpoint se lee en su router, igual que en Swagger y en los logs.
- Las URLs públicas no cambian (
/api/v1/catalogos/...). - Cada router nuevo debe incluir
/api/v1en suprefix; la prueba de OpenAPI del dominio lo detecta si falta. - Cumple el ADR 0016 transversal: la regla es la versión en el path, no dónde se declara.
Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.