En el desarrollo de software, una API rara vez permanece estática. Nuevos requerimientos del negocio, optimizaciones, mejoras de seguridad o cambios en el modelo de datos obligan a modificar la API con el tiempo. Pero si estos cambios se introducen sin cuidado, pueden romper integraciones de terceros, aplicaciones móviles, microservicios u otros clientes.

Aquí es donde entra el versionado de APIs: una estrategia esencial para permitir que una API evolucione de forma ordenada y sin romper la compatibilidad con los consumidores existentes.

 

¿Por qué versionar una API?

 

El versionado permite:

• Introducir cambios incompatibles sin afectar a los consumidores actuales.
• Dar tiempo a los clientes para migrar a la nueva versión.
• Mantener una documentación clara y coherente.
• Aplicar políticas de deprecación progresiva.

En otras palabras, es una forma controlada de decir: “mi API puede cambiar, pero no te voy a romper nada sin avisarte”.

 

¿Cuándo es necesario versionar?

 

Deberías considerar una nueva versión cuando introduces cambios incompatibles, como por ejemplo:

• Cambiar el nombre de una propiedad del JSON (firstName → nombre)
• Cambiar el tipo de respuesta (de objeto a arreglo)
• Requerir nuevos campos obligatorios en la petición
• Eliminar un campo o endpoint
• Modificar el comportamiento del endpoint (por ejemplo, un nuevo cálculo o lógica de negocio)

Cambios como agregar nuevos campos opcionales o nuevos endpoints no requieren versionado, si están bien diseñados.

 

Estrategias comunes de versionado

 

Existen varias formas de versionar una API. Aquí las más utilizadas:

 

1. Versionado por URL (Path versioning)

GET /v1/users
GET /v2/users

Ventajas:

• Muy explícito y fácil de entender
• Compatible con herramientas como Swagger, Postman, curl
• Los consumidores eligen claramente qué versión consumir

Desventajas:

• Las URLs quedan “contaminadas” con la versión
• Puede duplicar la documentación y los tests

Recomendado para: APIs públicas, integraciones de terceros, móviles

 

2. Versionado por header personalizado

GET /users
Accept: application/vnd.miempresa.v2+json

Ventajas:

• URLs limpias, independientes de la versión
• Buen control de formatos y evolución

Desventajas:

• Más difícil de probar con navegadores o herramientas simples
• Requiere más configuración en gateways o proxies

Recomendado para: APIs internas, clientes controlados, microservicios

 

3. Versionado por parámetro de query

GET /users?version=2

Ventajas:

• Fácil de implementar
• Compatible con navegadores y herramientas sencillas

Desventajas:

• Menos claro semánticamente (versionado no debería ser un filtro)
• No es considerado RESTful por algunos puristas

Recomendado para: Prototipos, entornos de prueba, APIs temporales

 

4. Versionado por subdominio

GET https://v1.api.miempresa.com/users

Ventajas:

• Aislamiento total por versión (útil en grandes ecosistemas)
• Permite distintas configuraciones por versión (seguridad, performance)

Desventajas:

• Infraestructura más compleja
• Mayor esfuerzo de mantenimiento

Recomendado para: Plataformas grandes, SaaS multi-versionadas, escenarios B2B

 

Buenas prácticas para versionar APIs

 

Versiona solo cuando sea necesario

No crees una nueva versión por cada cambio menor. Usa semver mental: 1.x.x para mejoras compatibles.

 

Documenta claramente cada versión

Usa Swagger/OpenAPI o Postman para que los consumidores entiendan qué cambió y cómo usarlo.

 

Establece un ciclo de vida para cada versión

Ejemplo: "Versión 1 estará disponible hasta diciembre de 2025."

 

Informa y educa a tus consumidores

Usa canales de comunicación, changelogs, correos o portales de desarrollador para anunciar deprecaciones.

 

Mantén el menor número posible de versiones activas

Evita mantener 4 o 5 versiones activas. Idealmente, una estable y otra en beta.

 

Conclusión

 

El versionado de APIs REST no es solo una decisión técnica, sino una decisión de diseño, experiencia de usuario y estrategia de evolución. Elegir una buena estrategia te permite:

• Evitar rupturas accidentales
• Mantener la confianza de tus integradores
• Evolucionar sin frenar tu producto

Ya sea que elijas versionado por URL, headers o subdominios, lo más importante es ser consistente, predecible y comunicativo con quienes consumen tu API.