Checklist de Versionado
Guía práctica para evaluar cambios en APIs y eventos — cómo distinguir cambios breaking de non-breaking y qué verificar antes de deployar.
¿Para qué un checklist?
Cada vez que modificás una API o un schema de evento, necesitás evaluar el impacto del cambio. Este checklist te ayuda a clasificar cambios, identificar riesgos y tomar las acciones correctas antes de que el cambio llegue a producción.
Clasificación de cambios
Cambios non-breaking (seguros)
Estos cambios son compatibles hacia atrás y generalmente se pueden deployar sin coordinación:
- ✅ Agregar un campo nuevo opcional a una respuesta de API
- ✅ Agregar un nuevo endpoint
- ✅ Agregar un parámetro de query opcional
- ✅ Agregar un campo nuevo opcional a un evento (con default)
- ✅ Agregar un nuevo tipo de evento
- ✅ Ampliar la documentación o descripciones
- ✅ Mejorar mensajes de error sin cambiar códigos de status
- ✅ Agregar nuevos códigos de status para casos no cubiertos antes
Cambios breaking (requieren coordinación)
Estos cambios rompen consumidores existentes y requieren una estrategia de migración:
- ❌ Eliminar un campo de una respuesta de API
- ❌ Renombrar un campo existente
- ❌ Cambiar el tipo de un campo (string → number, object → array)
- ❌ Hacer obligatorio un campo que era opcional
- ❌ Eliminar un endpoint
- ❌ Cambiar la URL de un endpoint
- ❌ Eliminar un campo de un evento
- ❌ Cambiar la semántica de un campo existente
- ❌ Reducir los valores aceptados en un enum
- ❌ Cambiar códigos de status HTTP para casos existentes
Cambios grises (evaluar caso por caso)
Estos cambios pueden o no ser breaking dependiendo del contexto:
- ⚠️ Agregar un nuevo valor a un enum — breaking si los consumidores hacen switch exhaustivo
- ⚠️ Cambiar un campo opcional a obligatorio en un request — breaking para consumidores que no lo enviaban
- ⚠️ Agregar validaciones más estrictas — breaking para consumidores que enviaban datos antes aceptados
- ⚠️ Cambiar el orden de campos en una respuesta — breaking si algún consumidor depende del orden
Checklist para cambios en APIs
Antes de deployar un cambio en una API, verificá cada punto:
1. Análisis de impacto
- ¿Identificaste todos los consumidores de este endpoint?
- ¿Revisaste los contract tests (si existen) para este endpoint?
- ¿El cambio es backward compatible?
- Si es breaking, ¿definiste una estrategia de migración?
2. Versionado
- ¿El cambio requiere una nueva versión de la API?
- Si es non-breaking, ¿se puede incluir en la versión actual?
- ¿Actualizaste la documentación de la API (OpenAPI/Swagger)?
- ¿Agregaste el cambio al changelog?
3. Comunicación
- ¿Notificaste a los equipos consumidores?
- Si es breaking, ¿definiste un período de coexistencia?
- ¿Agregaste headers de deprecación si corresponde?
- ¿La fecha de sunset está comunicada y documentada?
4. Testing
- ¿Los contract tests pasan con el cambio?
- ¿Probaste que los consumidores existentes siguen funcionando?
- ¿Agregaste tests para el nuevo comportamiento?
- ¿Ejecutaste can-i-deploy (o equivalente)?
5. Despliegue
- ¿El orden de deploy es correcto? (generalmente productor primero para non-breaking)
- ¿Tenés un plan de rollback si algo falla?
- ¿Configuraste monitoreo para detectar errores post-deploy?
Checklist para cambios en eventos
1. Análisis de compatibilidad
- ¿El cambio es backward compatible? (consumidores nuevos leen eventos viejos)
- ¿El cambio es forward compatible? (consumidores viejos leen eventos nuevos)
- ¿Los campos nuevos tienen valores por defecto?
- ¿Los consumidores existentes ignoran campos desconocidos?
2. Schema Registry
- ¿Registraste el schema nuevo en el schema registry?
- ¿La validación de compatibilidad pasó?
- ¿Actualizaste la versión del schema?
- ¿Documentaste los cambios en el schema?
3. Upcasting (si aplica)
- ¿Necesitás un upcaster para eventos históricos?
- ¿El upcaster es determinista y sin efectos secundarios?
- ¿Testeaste la cadena completa de upcasters?
- ¿Los consumidores que reprocesan eventos históricos funcionan correctamente?
4. Consumidores
- ¿Todos los consumidores pueden manejar el nuevo formato?
- ¿Los consumidores tienen manejo de errores para schemas inesperados?
- ¿El orden de deploy es correcto? (generalmente consumidores primero para backward compatible)
Proceso recomendado para cambios
Para cambios non-breaking
- Implementar el cambio en el productor
- Actualizar documentación y changelog
- Deployar el productor
- Notificar a consumidores sobre las nuevas capacidades
- Los consumidores adoptan el cambio a su ritmo
Para cambios breaking
- Comunicar el cambio con anticipación
- Crear la nueva versión (API) o schema (eventos)
- Implementar período de coexistencia
- Deployar la nueva versión junto a la anterior
- Coordinar migración de consumidores
- Monitorear adopción de la nueva versión
- Deprecar la versión anterior con fecha de sunset
- Retirar la versión anterior cuando no tenga tráfico
Señales de alerta
Prestá atención a estas señales que indican problemas en tu proceso de versionado:
- 🚩 No sabés cuántos consumidores tiene tu API
- 🚩 No tenés contract tests
- 🚩 Los cambios breaking se descubren en producción
- 🚩 No hay changelog ni documentación de versiones
- 🚩 Los equipos tienen miedo de cambiar APIs por no saber qué se rompe
- 🚩 Hay múltiples versiones activas sin fecha de sunset
- 🚩 Los eventos no tienen campo de versión en su schema