ADR-011: versionado de APIs y modelo de errores
Aceptado el 10/11/2026 por Andrés.
Decisión
- Versión mayor en la ruta (
/v1). Cambios compatibles no cambian versión. - Convivencia mínima de 6 meses entre versiones mayores, con cabeceras
DeprecationySunset. - El pipeline compara contratos y bloquea rupturas.
- Errores con Problem Details (RFC 9457) más
code,correlationIdyerrors. - Eventos con sobre CloudEvents 1.0; una ruptura crea un tópico
.v2.
Opciones descartadas
| Opción | Por qué no |
|---|---|
| Versión por cabecera o por tipo de contenido | Más difícil de probar, de enrutar y de explicar a un partner |
| Versión por fecha | Útil con muchos cambios pequeños; aquí sobra |
| Formato de error propio | Los partners ya tienen herramientas para el estándar |
Qué se sacrifica
La versión en la ruta invita a duplicar código al llegar /v2. Se mitiga traduciendo /v1 a /v2 en el borde del servicio.