Cuando la API evoluciona activamente, es importante mantener la compatibilidad entre versiones y evitar situaciones en las que un solo cambio rompa decenas de integraciones de clientes. Implementamos una versión completa de los contratos que permite controlar los cambios y actualizar las API sin ningún riesgo para los usuarios.
Esto es crítico en la arquitectura de microservicios, integraciones B2B y APIs abiertas, donde diferentes clientes utilizan diferentes versiones de interfaces.
Que estamos versionando
| Objeto | Descripción |
|---|---|
| Especificaciones OpenAPI | Almacenamos cada versión de la documentación y del contrato |
| Endpoint'ы | Agregamos versiones a la URL ('/v1/', '/v2/'), guardamos la compatibilidad backward |
| Contratos (Nat, Dredd) | Confirmación de las condiciones de interacción entre el cliente y el servidor |
| Modelos de datos | Controlar los cambios en la estructura de la consulta y la respuesta |
Cómo implementamos
Compatibilidad con múltiples versiones de API en paralelo
Especificación explícita de la versión en URL, encabezados o parámetros
Autovigilancia de cada versión de los contratos (Nat, Postman, Jest, Dredd)
Versionar las especificaciones en Git o a través de CI/CD
Documentación y changelog para los clientes cada vez que se realiza un cambio
Beneficios
Estabilidad garantizada de las integraciones
Posibilidad de lanzar nuevos fiches sin riesgo de «romper» a los clientes
Simplificar la migración entre versiones
Historial claro de cambios y control de contratos
Transparencia para equipos de desarrollo internos y externos
Donde es especialmente importante
Arquitectura de microservicios con múltiples dependencias
Plataformas con API pública o B2B
Sistemas financieros y de pago con contratos a largo plazo
Aplicaciones móviles que dependen de una API estable
La versificación de contratos es la base de la previsibilidad y la confianza en la API. Implementamos procesos que permiten cambiar y desarrollar la API sin dolor, manteniendo la interoperabilidad y la transparencia para todas las partes.