Por Que las APIs Necesitan Versionado
Las APIs evolucionan. Se agregan nuevas funcionalidades, los modelos de datos cambian y los patrones antiguos se reemplazan. Sin versionado, cualquier cambio podria romper clientes existentes. El versionado permite que cambios incompatibles coexistan con versiones anteriores.
Cambios Breaking vs. Non-Breaking
Cambios non-breaking (seguros sin nueva version):
- Agregar campos opcionales a respuestas
- Agregar nuevos endpoints
- Agregar query parameters opcionales
- Relajar reglas de validacion
Cambios breaking (requieren nueva version):
- Eliminar o renombrar un campo
- Cambiar el tipo de dato de un campo
- Hacer obligatorio un campo opcional
- Cambiar la estructura de URL
- Modificar mecanismos de autenticacion
Estrategias de Versionado
Versionado por URL Path
El enfoque mas comun:
GET /api/v1/users
GET /api/v2/users
Pros: Facil de ver, cachear y rutear Contras: URL cambia entre versiones
Versionado por Header
GET /api/users
Accept: application/vnd.myapi.v2+json
Pros: URLs limpias Contras: Oculto, mas dificil de debuggear
Versionado por Query Parameter
GET /api/users?version=2
Pros: Facil de cambiar, visible en URL Contras: Confuso con filtrado, complicaciones de cache
Comparacion
| Aspecto | URL Path | Header | Query Param |
|---|---|---|---|
| Visibilidad | Alta | Baja | Media |
| Caching | Facil | Complejo | Complejo |
| Ruteo en API gateway | Facil | Moderado | Moderado |
| Testing en navegador | Facil | Dificil | Facil |
| Adopcion en industria | Mas comun | Media | Menos comun |
Testing de Versionado de API
Tests de Compatibilidad Hacia Atras
Para cada nueva version, verifica que clientes existentes sigan funcionando:
- Estructura de response: Clientes v1 reciben formato v1
- Presencia de campos: Sin campos eliminados de v1
- Tipos de datos: Sin cambios de tipo en v1
- Formatos de error: Respuestas de error v1 sin cambios
- Autenticacion: Mecanismos v1 siguen funcionando
Tests Especificos por Version
| Test | v1 | v2 |
|---|---|---|
| GET /users response | {name: "Alice"} | {firstName: "Alice", lastName: "..."} |
| Paginacion | ?page=1&per_page=20 | ?cursor=abc&limit=20 |
| Formato de error | {error: "Not found"} | {error: {code: "NOT_FOUND", message: "..."}} |
Testing de Deprecacion
Cuando una version se esta deprecando, verifica:
- Headers de deprecacion presentes:
Deprecation: true
Sunset: Sat, 01 Mar 2026 00:00:00 GMT
Link: </api/v2/docs>; rel="successor-version"
- Headers de advertencia con info de deprecacion
- Links de documentacion en respuesta o headers
- Linea de tiempo de sunset: La version deprecated sigue funcionando hasta la fecha
- Despues del sunset: Retorna 410 Gone o redirige
Comportamiento de Version por Defecto
Testea que pasa sin version especificada:
- La API usa la ultima version?
- La API usa v1 (mas seguro)?
- La API retorna error requiriendo version explicita?
Consistencia de Datos entre Versiones
Datos creados en v1 deben ser accesibles en v2:
1. POST /api/v1/users → Crear usuario (formato v1)
2. GET /api/v2/users/{id} → Deberia retornar formato v2
3. PUT /api/v2/users/{id} → Actualizar en formato v2
4. GET /api/v1/users/{id} → Deberia retornar formato v1
Testing de Migracion
Al migrar clientes de v1 a v2:
- Verificar que toda funcionalidad v1 tiene equivalentes v2
- Testear transformacion de datos v1 en respuestas v2
- Verificar alternativas documentadas para features eliminados
- Asegurar que tokens funcionan en ambas versiones
Bugs Comunes de Versionado
| Bug | Como Detectarlo |
|---|---|
| v1 incluye campos de v2 | Comparar schema v1 con docs |
| v2 rompe contrato v1 | Ejecutar suite v1 contra deployment actual |
| Sin aviso de deprecacion | Verificar headers de versiones deprecated |
| Inconsistencia de datos | Crear en v1, leer en v2, comparar |
| Version default cambia | Testear requests sin version explicita |
Ejercicio Practico
- Compara versiones: Si usas API con multiples versiones, compara la misma operacion entre versiones.
- Testea compatibilidad: Haz requests a ambas versiones y verifica consistencia de datos.
- Crea checklist de migracion: Para migracion hipotetica v1 a v2, lista cambios y sus tests.
- Verifica deprecacion: Busca endpoint deprecated y verifica headers apropiados.
Puntos Clave
- El versionado permite cambios incompatibles mientras mantiene clientes existentes funcionales
- URL path versioning es el mas comun; header versioning el mas REST-compatible
- Breaking changes requieren nuevas versiones; non-breaking changes no
- Testea compatibilidad hacia atras ejecutando suites antiguas contra nuevos deployments
- Verifica comunicacion de deprecacion: headers, fechas de sunset y guias de migracion