Las API evolucionan. Nuevas funciones, correcciones, obsolescencias. Pero los clientes dependen de la interfaz actual. El control de versiones permite la evolución sin romper las aplicaciones existentes. Esta guía presenta estrategias y mejores prácticas.
Por qué versión
Compatibilidad
Los antiguos clientes siguen trabajando.
Evolución
Mejora sin bloquear.
Documentación
Claridad sobre qué esperar.
Transición
Es hora de que los clientes migren.
Cuándo realizar la versión
Cambios importantes
Cambios que rompen contratos.
Ejemplos
- Eliminar campo
- Cambiar tipo de datos
- Cambiar significado
- Eliminar punto final
No versionar para
Adiciones, que generalmente son compatibles.
Estrategias de control de versiones
Ruta URL
/api/v1/usuarios, /api/v2/usuarios.
Parámetro de consulta
/api/users?version=1.
Encabezado
Accept-Version: v1 o API-Version: 2.
Negociación de contenidos
Accept: application/vnd.myapi.v1+json.
Control de versiones de ruta URL
Ventajas
Visible, claro y fácil de enrutar.
Desventajas
Las URL cambian con la versión.
Ejemplo
OBTENER /api/v1/productos OBTENER /api/v2/productos
Común
Enfoque más popular.
Versiones del encabezado
Ventajas
URL limpias y semánticamente correctas.
Desventajas
Menos visible, más difícil de probar.
Ejemplo
OBTENER /api/productos Encabezado: API-Versión: 2
Versionado semántico
Formato
PARCHE.MAYOR.MENOR.
MAYOR
Cambios radicales.
MENOR
Adiciones compatibles.
PARCHE
Bichos geniales.
Para API
Generalmente solo MAYOR en la versión pública.
Depreciación
Proceso
Marcar como obsoleto antes de eliminarlo.
Comunicación
Encabezados, documentación, registro de cambios.
Cronología
Plazo de migración.
Soporte
Cuánto tiempo permanecer en desuso.
Encabezados del atardecer
Encabezado HTTP
Sunset: Sat, 01 Jul 2024 00:00:00 GMT.
Encabezado de obsolescencia
Indica que está en desuso.
Comunicación
Los clientes pueden detectar automáticamente.
Migración
Documentación
Qué cambió, cómo adaptarse.
Guías
Migración paso a paso.
Soporte
Ayuda durante la transición.
Cronología
Plazo razonable.
Compatibilidad con versiones anteriores
Objetivo
Los nuevos clientes, las antiguas API funcionan.
Aditivo
Añadir, no quitar.
Valores predeterminados
Nuevos campos con valores predeterminados.
###Opcional
Nuevos parámetros opcionales.
Compatibilidad futura
Concepto
Clientes antiguos con nuevas API.
Ignorar desconocido
Ignora los campos desconocidos.
Degradación elegante
Trabaja sin nuevas funciones.
Diseño para la evolución
Extensibilidad
Piense en cambios futuros.
Estructuras genéricas
Objetos extensibles.
Indicadores de funciones
No exponga características incompletas.
Contratos
Defina claramente lo que promete.
Múltiples versiones
Mantenimiento
Costo de mantenimiento de varios.
Límites
Cuántos apoyar simultáneamente.
Política
Establece reglas claras.
Documentación
Por versión
Documentos específicos de la versión.
Registro de cambios
Qué cambió entre versiones.
Guías de migración
Cómo actualizar.
Avisos de desuso
Que saldrá.
Herramientas
API abierta/Swagger
Especificación versionada.
cartero
Colecciones por versión.
Puertas de enlace API
Enrutamiento de versiones.
Errores comunes
Versión demasiada
Nueva versión para cada cambio.
No versionar
Cambio importante sin nueva versión.
Desaprobar rápido
No dar tiempo a la migración.
Sin comunicación
Clientes sorprendidos por los cambios.
SDK y clientes
Versiones correspondientes
SDK v1 para API v1.
Mantenimiento
Mantenga los SDK actualizados.
Comunicación
Notificar sobre nuevas versiones.
Conclusión
El control de versiones de API es una disciplina a largo plazo. Elija una estrategia clara, comunique los cambios y dé tiempo para la migración. El resultado son API que evolucionan sin romper las integraciones.
##Preguntas frecuentes
1) ¿Qué estrategia de control de versiones utilizar? La ruta URL es la más común y recomendada para la mayoría.
2) ¿Cuándo aumentar la versión principal? Para cambios importantes que no son compatibles con versiones anteriores.
3) ¿Cuánto tiempo durará la compatibilidad con la versión anterior? 6-12 meses es común. Depende de los clientes.
4) ¿Puedo realizar cambios sin versionar? Adiciones generalmente sí. Sin mudanzas/cambios.
5) ¿Cómo informar la baja? Encabezados, documentos, correos electrónicos, período de transición.
Lea también
- GraphQL para aplicaciones: Guía de implementación
- Backend para Aplicaciones: Arquitectura, Tecnologías y Mejores Prácticas
- Microservicios en Aplicaciones: Arquitectura Distribuida para Móviles
- API para aplicaciones
- API para Aplicaciones - Paso a Paso en la Vida Cotidiana
- API para Aplicaciones - Paso a Paso hacia el Escalado