Pular para o conteúdo principal

ADR 0004 — Versionamento URI /v1 e rotas VERSION_NEUTRAL

  • Status: Aceite
  • Data: 2026-03

Contexto​

Clientes (front admin, CRM, Caddy, Postman) já apontavam para paths sem /v1 em cadastro, branding e roles (/api/centralcrm/..., /api/centralbackend/..., /api/users/...). Quebrar esses contratos no mesmo release da API versionada não era opção.

Decisão​

  • Prefixo global api + VersioningType.URI → contratos novos em /api/v1/....
  • Controllers legados ou de integração usam VERSION_NEUTRAL (sem segmento de versão).
  • OpenAPI descreve ambos.

Consequências​

  • Positivo: evolução de DTOs em v2 sem matar o cadastro/branding atual.
  • Negativo: dois “mundos” de path; o catálogo tem de listar os dois. Preferir /api/v1/auth/users em código novo; /api/users fica legado.