Una API rara vez permanece igual: aparecen nuevas necesidades, cambian los datos y se corrigen decisiones de diseño. El problema surge cuando esos cambios afectan a aplicaciones que ya dependen de ella. Una modificación aparentemente pequeña puede provocar errores en procesos de pago, informes o integraciones que funcionan sin supervisión constante.
Versionar una API permite introducir cambios incompatibles sin obligar a todos los consumidores a adaptarse al mismo tiempo. En esta guía aprenderás a distinguir cambios compatibles de cambios disruptivos, elegir una estrategia de versionado y planificar una migración con pruebas, seguimiento y retirada controlada.
Qué significa versionar una API
Versionar una API consiste en identificar y mantener distintas formas de su contrato. Ese contrato incluye las rutas, los métodos HTTP, los parámetros, la estructura de las respuestas, los códigos de estado y también comportamientos como la paginación o los límites aplicables.
Por ejemplo, si una aplicación espera que el campo precio sea un número y la API comienza a devolver una cadena, la integración puede fallar aunque la ruta no haya cambiado. Una nueva versión permite ofrecer el nuevo formato mientras la anterior conserva el comportamiento esperado.
El versionado no elimina por sí solo las interrupciones: hay que mantener el contrato antiguo, probarlo y dar tiempo a los consumidores para migrar. También conviene evitar crear una versión nueva por cada ajuste interno que no afecte al contrato público.
Identifica los cambios que pueden romper integraciones
Antes de elegir cómo nombrar una versión, determina qué cambios afectan a los clientes existentes. Una clasificación útil distingue entre cambios compatibles y cambios incompatibles, aunque la compatibilidad real depende de cómo estén construidos los consumidores.
Cambios habitualmente compatibles
Algunos cambios suelen poder incorporarse sin crear una versión mayor:
- Añadir un nuevo endpoint sin modificar los existentes.
- Incorporar un campo opcional a una solicitud.
- Añadir un campo a una respuesta, siempre que los clientes toleren propiedades desconocidas.
- Corregir un error sin alterar el comportamiento del que dependen los consumidores.
Estas situaciones requieren pruebas. Por ejemplo, un cliente con validación estricta podría rechazar una propiedad adicional. Del mismo modo, corregir un error puede romper una integración que se había adaptado a él. Documenta estas dependencias antes de dar por segura una modificación.
Cambios potencialmente incompatibles
Considera disruptivos, entre otros, los siguientes cambios:
- Eliminar o renombrar campos, rutas o parámetros.
- Cambiar el tipo, el significado o la unidad de un dato.
- Convertir un parámetro opcional en obligatorio.
- Modificar la autenticación, los permisos o los códigos de error esperados.
- Cambiar el orden, la paginación o las reglas de filtrado de una respuesta.
- Reducir límites de uso o tiempos de espera de manera que afecte a procesos existentes.
Añadir un valor a una enumeración también puede causar fallos si un cliente solo acepta los valores conocidos. La regla práctica es evaluar el efecto observable, no solo el tamaño del cambio en el código.
Elige una estrategia de versionado
No existe una única forma correcta de identificar versiones. La elección depende de la facilidad de uso, la infraestructura y las expectativas de los consumidores. Lo importante es aplicar el criterio de forma consistente y documentarlo.
Versión en la URL
Una opción frecuente es incluir la versión en la ruta, por ejemplo, /v1/pedidos y /v2/pedidos. Resulta fácil de identificar en la documentación, los registros y las pruebas. También facilita dirigir el tráfico a implementaciones distintas.
Como contrapartida, cambia la dirección del recurso y puede ser necesario actualizar clientes, reglas de caché y configuración de pasarelas. Si eliges este enfoque, mantén disponible la ruta anterior durante el periodo de transición acordado.
Versión en una cabecera HTTP
Otra posibilidad es solicitar la versión mediante una cabecera, como API-Version: 2. La ruta permanece estable y la versión forma parte de la petición. Esto puede ser útil cuando se quiere separar la identificación del recurso de la negociación del contrato.
La desventaja es que la versión resulta menos visible al inspeccionar una URL. Además, las herramientas intermedias y las cachés deben configurarse para distinguir las respuestas según la cabecera utilizada. En cachés HTTP, revisa el uso de Vary cuando corresponda y comprueba que las pasarelas no eliminen la cabecera.
También es posible usar parámetros de consulta o negociar el formato mediante Accept. En cualquier caso, define qué sucede si falta la versión o se solicita una inexistente. Evita que un cliente sin versión explícita cambie silenciosamente a un contrato incompatible.
Define una política de compatibilidad
Una política pública reduce la incertidumbre tanto para el equipo como para quienes integran la API. No tiene que ser extensa, pero sí responder a preguntas concretas:
- Qué se considera incompatible: especifica qué cambios requieren una nueva versión.
- Cuánto soporte recibe cada versión: establece un plazo o criterio de retirada realista.
- Cómo se comunican los cambios: indica dónde se publican avisos y notas de versión.
- Qué ocurre durante una incidencia: explica cómo se gestionan las correcciones urgentes en versiones activas.
- Cómo se identifica al consumidor: utiliza credenciales o identificadores apropiados para conocer qué versión utiliza cada integración.
Puedes inspirarte en el versionado semántico para comunicar la magnitud de los cambios, pero un número por sí solo no garantiza compatibilidad. Define qué significan las versiones para tu API y cómo se relacionan con los cambios del contrato.
La política también debe contemplar excepciones de seguridad. Mantener compatibilidad no implica conservar indefinidamente una vulnerabilidad: prepara un procedimiento para corregirla y comunicar el impacto con la mayor antelación posible.
Planifica la migración sin detener el servicio
Una migración segura comienza antes de publicar la nueva versión. Primero identifica a los consumidores, sus rutas más utilizadas y las diferencias entre contratos. Si hay clientes externos, proporciona una guía que describa qué deben cambiar y cómo comprobarlo.
Supongamos que /v1/pedidos devuelve precio como número y que la nueva versión necesita devolver importe y moneda por separado. La guía debería mostrar ambos formatos, explicar la conversión y señalar cómo tratar pedidos antiguos que no tengan moneda explícita.
Después, sigue una secuencia como esta:
- Publica la nueva versión en paralelo. Mantén la anterior con su contrato y comportamiento conocidos.
- Ofrece documentación y ejemplos. Incluye autenticación, errores, límites y diferencias relevantes, no solo respuestas satisfactorias.
- Habilita un entorno de pruebas. Permite validar solicitudes y errores sin afectar a operaciones reales, cuando sea viable.
- Invita a migrar gradualmente. Comienza con integraciones controladas y amplía el uso tras revisar los resultados.
- Supervisa ambas versiones. Detecta errores, latencia y consumidores que todavía dependen de la anterior.
- Retira la versión antigua de forma anunciada. Hazlo solo después de comprobar el impacto y seguir la política publicada.
Si usas adaptadores para traducir entre contratos, verifica que no introduzcan pérdidas de información ni cambien reglas de negocio. Mantener dos versiones también tiene un coste: procura compartir componentes internos cuando sea seguro, sin alterar el comportamiento externo de la versión antigua.
Prueba el contrato y observa el uso real
Las pruebas unitarias no bastan para proteger una integración. Añade pruebas de contrato que comprueben solicitudes, respuestas y errores relevantes desde la perspectiva del consumidor. Una descripción OpenAPI puede servir como referencia, pero debe mantenerse actualizada y complementarse con pruebas de comportamiento.
Incluye casos que suelen pasar desapercibidos: campos ausentes o nulos, listas vacías, valores desconocidos, paginación, autenticación fallida, reintentos y límites de uso. Siempre que sea posible, ejecuta también pruebas de integración con clientes representativos y conserva pruebas de regresión para la versión anterior.
En producción, observa métricas por versión y por consumidor: volumen de solicitudes, errores, latencia y uso de rutas que planeas retirar. Evita registrar secretos o datos personales innecesarios; limita el acceso y la retención de los registros según corresponda.
Para el despliegue, usa una liberación gradual y define criterios de reversión antes de empezar. La reversión debe contemplar tanto la aplicación como los cambios de datos. Por ejemplo, una migración de base de datos incompatible puede impedir volver atrás aunque puedas restaurar el código anterior.
Comunica la retirada de una versión
Una versión obsoleta no es necesariamente una versión retirada. Primero anuncia que dejará de recibir soporte, explica el motivo, publica la fecha prevista de retirada y proporciona instrucciones de migración. Contacta directamente con los consumidores identificados y recuerda el aviso antes del cierre.
Puedes complementar la comunicación con cabeceras HTTP, como Sunset, cuando estén implementadas correctamente, pero no dependas solo de ellas: algunos clientes no las revisan. Mantén la información en un canal documentado y accesible.
Antes de desactivar la versión, revisa el tráfico restante y confirma qué integraciones siguen utilizándola. Si existe uso significativo, evalúa el impacto y ajusta el plan cuando sea necesario. Al retirarla, devuelve una respuesta clara y documentada en lugar de permitir fallos ambiguos.
Conclusión
Versionar una API sin interrumpir las integraciones existentes exige más que añadir un número a una ruta. Hay que reconocer los cambios incompatibles, conservar el contrato anterior, probar ambos comportamientos y acompañar a los consumidores durante la transición.
Empieza por revisar el contrato de tu API y las integraciones que dependen de él. Con esa información podrás elegir una estrategia de versionado, establecer una política de soporte y preparar migraciones más predecibles.
