Manos conectando cables de red para la gestión de versiones de API

Versionar una API significa publicar un identificador estable para cada conjunto de contratos que ofreces a tus consumidores. Para la mayoría de APIs públicas, la recomendación práctica es usar el versionado en la ruta, gestionar internamente con versionado semántico y anunciar cualquier deprecación con un plazo mínimo de seis meses antes del apagado definitivo.

En resumen:

  • Solo se debería crear una nueva versión cuando un cambio rompe la compatibilidad con clientes existentes, como eliminar campos o cambiar tipos de datos.
  • El versionado en la ruta es la estrategia más recomendable por su simplicidad en pruebas, documentación y gobierno de varias versiones.
  • La gestión del ciclo de vida incluye definir fechas de sunset, usar cabeceras de deprecación y mantener versiones activas al menos seis meses.
  • Exponer solo el número MAJOR en la ruta evita confusiones y facilitar el soporte, reservando el MINOR y PATCH para registros internos y cambios no disruptivos.
  • Es clave planificar la gobernanza, fijar plazos de retiro y comunicar claramente las fechas y cambios a los usuarios para evitar acumulación de deuda técnica.

Tabla de contenidos

Estrategias de versionado de APIs: path, header, query y content negotiation

Cada estrategia de versionado resuelve un problema distinto, y elegir mal te va a costar caro en soporte y en confusión de tus consumidores. El versionado en ruta (/v1/pedidos, /v2/pedidos) es el más extendido porque es visible, cacheable y fácil de documentar en herramientas como OpenAPI o Swagger. Azure API Management trata cada versión publicada en la ruta como una API independiente dentro del mismo portal, lo que simplifica el gobierno cuando mantienes varias en paralelo.

El versionado por cabecera (header) es más limpio desde el punto de vista de las URLs, pero complica el testing manual y el caching en proxies intermedios, porque dos peticiones a la misma URL pueden devolver respuestas distintas según el encabezado enviado.

Estas son las diferencias que importan a la hora de decidir:

  • Versionado en ruta: máxima visibilidad, fácil de probar con cualquier navegador o cliente REST, ideal para APIs públicas.
  • Versionado por cabecera: URLs limpias, pero exige documentación explícita para que el consumidor sepa qué enviar.
  • Versionado por parámetro de consulta: útil para pruebas rápidas o migraciones graduales, aunque tiende a ensuciar los registros de acceso.
  • Negociación de contenido (Accept: application/vnd.empresa.v2+json): elegante desde la teoría REST, pero poco intuitiva para equipos que no viven la especificación HTTP a diario.

Para casi cualquier equipo, versionar en la ruta reduce fricción en debugging y en la generación automática de documentación, algo que las guías de diseño de APIs llevan años señalando como ventaja práctica frente a alternativas más puristas.

¿Cuándo hay que crear una nueva versión de una API?

La regla es simple: creas una nueva versión cuando el cambio rompe algo que un cliente ya está usando. El problema es que «romper algo» no siempre es obvio hasta que revisas los contratos con detalle.

Estos son ejemplos claros de breaking changes que exigen nueva versión, según recogen las guías de ciclo de vida de APIs:

  1. Eliminar o renombrar un campo de la respuesta.
  2. Cambiar el tipo de dato de un campo (de cadena a número, por ejemplo).
  3. Añadir un parámetro obligatorio que antes no existía.
  4. Cambiar el código de estado HTTP que devuelve un endpoint en un caso ya documentado.
  5. Modificar el comportamiento por defecto de un endpoint sin que el cliente lo solicite.

En cambio, estos cambios no deberían disparar una nueva versión:

  1. Añadir un campo opcional a la respuesta.
  2. Publicar un endpoint completamente nuevo.
  3. Corregir un error interno que no altera el contrato público.
  4. Mejorar el rendimiento sin tocar la forma de la respuesta.

Antes de publicar cualquier cambio, pregúntate: ¿un cliente que integró hace seis meses seguiría funcionando sin tocar su código? Si la respuesta es no, necesitas gestionar bien la integración antes de sacar nada a producción.

Versionado semántico aplicado a APIs: qué significa cada número

El versionado semántico (SemVer) usa el formato MAJOR.MINOR.PATCH, y trasladarlo a una API tiene su lógica propia:

  • MAJOR sube cuando introduces un breaking change: es el número que verá tu cliente en la URL o en la documentación pública.
  • MINOR sube cuando añades funcionalidad compatible hacia atrás, como un endpoint nuevo o un campo opcional.
  • PATCH sube con correcciones internas que no cambian el contrato, y normalmente el consumidor ni se entera.

En la práctica, casi ningún consumidor necesita ver el PATCH. Por eso muchas empresas exponen solo el MAJOR en la ruta (/v2/) y reservan el MINOR y el PATCH para el registro de cambios (changelog) y los SDK internos. Esta separación entre versión visible y revisión interna es exactamente lo que recomienda Microsoft en su documentación sobre mantenimiento de microservicios: versiones para lo incompatible, revisiones para lo demás.

Deprecación y sunset: cómo comunicar el fin de una versión sin sorpresas

Deprecación y sunset no son sinónimos, y confundirlos genera tickets de soporte innecesarios. La deprecación anuncia que una versión dejará de recibir mejoras; el sunset es la fecha real en que deja de responder.

Los estándares HTTP y las guías de ciclo de vida recomiendan usar cabeceras explícitas para que los clientes automatizados detecten el cambio sin depender de que alguien lea un correo:

  • Deprecation: true o Deprecation: <fecha> para marcar que la versión entra en fase de retirada.
  • Sunset: <fecha HTTP> para indicar el momento exacto en que la versión dejará de funcionar.
  • Link: <URL>; rel="successor-version" para apuntar directamente a la versión que debe usarse en su lugar.

Consejo profesional: añade estas cabeceras incluso antes de tener fecha de sunset confirmada; el simple hecho de marcar Deprecation: true empuja a los equipos integradores a planificar la migración con tiempo.

Sobre los plazos, la práctica extendida y recogida por Zuplo es mantener una versión deprecada operativa un mínimo de seis meses antes de apagarla, y extender ese plazo hasta 12 o 24 meses en APIs públicas con muchos consumidores externos. La norma española NOR_API va en la misma dirección: recomienda versionado semántico, mantener versiones en paralelo y notificar formalmente cada publicación.

Cronograma y estrategias para la descontinuación y retiro de versiones de API

Cuando llega el sunset, tienes tres salidas razonables: devolver un 410 Gone explícito, redirigir automáticamente al nuevo endpoint, o mantener un proxy temporal que traduzca peticiones antiguas al nuevo contrato mientras monitorizas si queda tráfico real.

Ciclo de vida de una versión y gobernanza técnica

Una versión de API atraviesa fases predecibles: diseño, disponibilidad general (GA), mantenimiento activo, deprecación y sunset. Tratar cada fase como un estado formal, con criterios de entrada y salida, evita que una versión quede «viva» de forma indefinida por inercia.

A nivel de gobernanza, conviene fijar reglas claras desde el principio:

  • Define un número razonable de versiones paralelas que tu equipo soportará, que suele ser pocas para la mayoría de organizaciones.
  • Audita la seguridad de cada versión activa, no solo de la más reciente: una versión antigua olvidada es una puerta de entrada.
  • Aplica el enfoque Contract-First: define el contrato antes de escribir código, algo especialmente valioso en APIs públicas y SDKs.
  • Versiona por conjunto de API (API Set) y no endpoint a endpoint, para evitar que dos recursos relacionados queden en versiones distintas sin sentido.

Consejo profesional: escribe pruebas automatizadas específicas por versión, no solo por endpoint; así detectas si un cambio en v2 rompe silenciosamente algo que v1 seguía necesitando.

Patrones de migración: qué hacer esta semana con tu API

Convertir estas ideas en acción no requiere una reestructuración completa, sino disciplina en cada publicación. Esta secuencia funciona bien como punto de partida:

  1. Documenta cada endpoint con su versión, changelog y fecha estimada de deprecación si aplica.
  2. Añade pruebas automatizadas por versión antes de tocar el código de producción; una guía de pruebas de API te ahorra descubrir el problema en producción.
  3. Usa feature flags para activar funcionalidad nueva de forma gradual sin forzar un salto de versión mayor.
  4. Define una estrategia de rollback clara: si v2 falla en producción, ¿cuánto tarda el equipo en volver a v1 sin perder datos?
  5. Coordina con los equipos consumidores antes de anunciar cualquier deprecación, no después.

La decisión de versionar es tanto de producto como técnica: mantener versiones coexistentes da tiempo real a tus clientes para migrar, en lugar de forzarles un cambio de un día para otro.

Este último punto es el que peor gestionan los equipos técnicos: tratar el versionado como un problema exclusivamente de código, cuando en realidad es una negociación con quien consume tu API. La interoperabilidad entre sistemas depende tanto de la comunicación como del diseño técnico.

Cómo aborda Codentix el versionado en integraciones empresariales

Diseñar contratos de API estables es parte del trabajo diario cuando conectas sistemas empresariales entre sí. Codentix construye e integra APIs para empresas que necesitan que sus sistemas de CRM, ERP y herramientas internas se comuniquen sin que una actualización rompa el flujo de trabajo del día siguiente.

Ese trabajo incluye definir estrategias de versionado desde el diseño inicial del contrato, no como un parche posterior. La guía de integración de herramientas digitales de Codentix recoge cómo se aplican estos principios en proyectos reales de conexión entre plataformas empresariales, y el equipo ofrece servicios de integración de sistemas y APIs pensados precisamente para evitar el tipo de rupturas que un mal versionado provoca.

Lo que la mayoría de equipos hace mal con el versionado

Lo que la mayoría de equipos hace mal con el versionado — overview diagram

La conversación sobre versionado suele centrarse en la sintaxis: ¿path o header?, ¿v1 o v2 en la URL? Esa discusión, aunque legítima, esconde el problema real: casi ningún equipo define de antemano cuánto tiempo va a mantener una versión viva ni quién es responsable de monitorizar su uso antes de apagarla.

He visto equipos técnicos excelentes construir una v2 impecable y luego dejar la v1 corriendo durante años porque nadie se atrevió a fijar una fecha de sunset. El coste no es solo técnico, es organizativo: cada versión sin plazo de retirada es una decisión de gobernanza pendiente que alguien más va a tener que tomar bajo presión.

Mi recomendación real, más allá de la teoría de SemVer, es tratar la fecha de sunset como parte del contrato desde el día en que publicas una versión, no como una decisión que se toma cuando ya molesta mantenerla. Las herramientas y los estándares ayudan, pero la disciplina de fijar plazos y comunicarlos con antelación es lo que realmente separa una API bien versionada de una que acumula deuda técnica silenciosa.

— Joan Jimenez Jané

Cuando versionar bien tu API no es suficiente y necesitas ayuda experta

Codentix es la alternativa a resolver el versionado de APIs por prueba y error: en lugar de improvisar contratos y descubrir los breaking changes cuando ya afectaron a un cliente, el equipo diseña la estrategia de versionado como parte del proyecto de integración desde el primer día.

Codentix

Si tu empresa depende de que varios sistemas (CRM, ERP, plataformas propias) se hablen entre sí sin romperse con cada actualización, Codentix ofrece desarrollo de software a medida que incluye precisamente ese trabajo de definir contratos estables, planificar migraciones y establecer plazos de deprecación razonables para tus consumidores internos y externos. Esto encaja especialmente bien si acabas de leer este artículo y te has dado cuenta de que tu API actual no tiene ni versión explícita ni fecha de retirada para nada.

Solicita una consulta con Codentix para revisar cómo está versionada tu API actual y qué cambios necesita antes de tu próxima integración.

Fuentes

Para consultar el detalle técnico completo, revisa la documentación de versiones en Azure API Management, la guía de ciclo de vida y versionado de APIs y la normativa NOR_API v01r01.

Recomendaciones