Saltar a contenido

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.py monta los routers sin prefix (application.include_router(catalogos_router)); se elimina la constante PREFIJO_API.
  • Si un dominio necesita una versión nueva, la declara en su propio router (/api/v2/<dominio>) sin tocar main.py ni 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/v1 en main.py y /catalogos en 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/v1 en su prefix; 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.