Definición: Estrategia para gestionar cambios en una API sin romper la compatibilidad con los clientes existentes, permitiendo la evolucion controlada de la interfaz publica.
— Fuente: NERVICO, Consultoría de Desarrollo de Producto
Que es el versionado de API
El versionado de API es la practica de gestionar diferentes versiones de una interfaz de programacion para permitir su evolucion sin romper la compatibilidad con los clientes existentes. Cuando una API necesita cambios incompatibles (breaking changes), se publica una nueva version mientras se mantiene la anterior durante un periodo de transicion, dando tiempo a los consumidores para migrar.
Como funciona
Existen tres estrategias principales. El versionado por URL incluye la version en la ruta (api/v1/users, api/v2/users) y es la mas visible y facil de implementar. El versionado por header utiliza un encabezado HTTP personalizado (Accept: application/vnd.api+json;version=2) para seleccionar la version. El versionado por query parameter anade la version como parametro (api/users?version=2). Independientemente de la estrategia, es fundamental documentar las diferencias entre versiones, establecer politicas claras de deprecacion y comunicar los plazos de fin de vida de versiones antiguas.
Casos de uso principales
- Evolucion de APIs publicas consumidas por clientes externos que no pueden actualizar simultaneamente
- Migracion gradual de esquemas de respuesta en APIs internas entre equipos de microservicios
- Lanzamiento de nuevas versiones de endpoints con funcionalidad mejorada sin afectar a integraciones existentes
- Gestion del ciclo de vida de APIs en plataformas SaaS con multiples versiones de clientes moviles en circulacion
Ventajas y consideraciones
El versionado permite evolucionar APIs de forma segura y predecible, dando a los consumidores control sobre cuando adoptar los cambios. Es especialmente critico en APIs publicas y ecosistemas con muchos integradores. La principal consideracion es el coste de mantener multiples versiones simultaneamente, incluyendo la complejidad del codigo, las pruebas y la documentacion. Es recomendable minimizar los breaking changes y favorecer cambios aditivos que no requieran nueva version.