API versioning: cómo evitar que tu workflow se rompa

Qué es API versioning y por qué tu workflow puede romperse sin aviso

Una integración de API puede funcionar perfecto durante meses. Después el proveedor decide mejorar sus endpoints, cambia el formato de las respuestas y retira el comportamiento de la versión anterior. Si ese breaking change llega a producción antes de que tu workflow esté listo, los pasos siguientes del proceso reciben datos equivocados sin que nadie lo note hasta que el daño ya está hecho.

El API versioning reduce ese riesgo separando los cambios incompatibles de la versión que tu integración ya usa. Al mantener disponible el comportamiento antiguo mientras introduce una versión nueva, el proveedor te da tiempo para actualizar, probar y migrar a tu propio ritmo.

En términos concretos: versionar una API es mantener distintas versiones de la misma interfaz para que el proveedor pueda cambiar su funcionamiento sin obligar a toda integración existente a actualizarse el mismo día del lanzamiento. Cada versión representa una interfaz que tu workflow ya conoce: cuándo están disponibles los endpoints, qué datos aceptan o devuelven y cómo se comportan las peticiones y las respuestas.

Cuando dependes de una API de terceros, el proveedor decide cuándo salen las versiones nuevas y los cambios incompatibles. Anclar tu integración a una versión específica es lo que te compra tiempo para revisar y migrar. Lo mismo aplica al REST API versioning: si un cambio es retrocompatible, la integración sigue funcionando sin modificaciones; el versionado entra en juego justo cuando esa retrocompatibilidad se rompe.

Las cuatro estrategias de versionado que verás en APIs de terceros

El diseño del proveedor decide cuál de estos enfoques se usa. Tu trabajo no es elegirlo, sino entender dónde vive la versión y qué implica para tu integración.

1. URI versioning (la versión en la URL)

La versión aparece directamente en la URL de la API: una versión puede usar una estructura con v1 y la nueva, v2, como en /v1/products. La ventaja es la visibilidad: ves la versión activa en el workflow, en los logs y en la documentación. Si una petición falla o devuelve datos con un formato inesperado, miras la URL y confirmas qué versión se usó, sin buscar en otra parte de la petición. Además, al tener cada versión su propia URL, los sistemas de caché las distinguen con facilidad.

2. Header versioning (la versión en un encabezado)

Aquí la URL no cambia y el workflow envía la versión en un encabezado HTTP. Un encabezado es información extra adjunta a la petición —como credenciales de autenticación o tipo de dato— y le indica al proveedor qué versión quieres usar. La URL se mantiene estable, pero la versión se vuelve menos visible: si la API empieza a devolver datos raros, mirar la URL no te dirá qué versión procesó la petición. Hay un segundo efecto: los sistemas de caché deben considerar el encabezado de versión, porque dos peticiones pueden usar la misma URL y pedir versiones distintas.

3. Date-based versioning (la versión como fecha)

El proveedor identifica la versión por su fecha de lanzamiento en lugar de un número como v1 o v2. Es distinto del semantic versioning, donde la versión se expresa como 2.1.0 para distinguir releases mayores, menores y parches. Si tu workflow usa una versión con fecha, puedes compararla con las notas de release del proveedor para ver cómo los cambios posteriores afectan tu integración. Ojo: la fecha no explica los cambios por sí sola. Hay que revisar la documentación y probar la versión nueva antes de cambiar. Algunos proveedores envían la fecha por encabezado HTTP, así que este modelo puede combinarse con el header versioning.

4. Query parameter versioning (la versión como parámetro)

La versión va como un parámetro extra al final de la URL, por ejemplo example-api.com/products?version=v1. La parte principal de la URL no cambia y el parámetro le dice al proveedor qué versión debe procesar la petición. Sigue siendo visible al inspeccionar la petición: ves qué recurso pidió el workflow y con qué versión, sin revisar un encabezado aparte. El riesgo está en la caché: puede ver dos URLs que difieren solo en el parámetro de versión aunque devuelvan datos distintos. Si ignora el parámetro, puede servir una respuesta de la versión equivocada. La mitigación es fijar el parámetro de versión en tu integración y asegurarte de que los sistemas que procesan esas peticiones puedan distinguirlas.

Cómo saber si una versión está por morir: deprecation y sunset headers

Una estrategia de deprecación sólida empieza por monitorear encabezados y metadatos en busca de señales de retiro. El deprecation header suele ser el primer aviso: indica que la versión está o estará obsoleta. Deberías marcar la integración para migración antes de que deje de funcionar, incluso si la API todavía responde con normalidad.

El sunset header añade algo más valioso: una fecha exacta de cuándo se espera que la versión deje de estar disponible. Ese es el plazo real que tienes para probar y cambiar de versión.

Pasado ese punto, el proveedor puede devolver 410 Gone, que significa que el recurso solicitado ya no está disponible y que la condición probablemente sea permanente. La reacción correcta no es reintentar la misma versión ni repetir la petición: el workflow debe detectar esa respuesta y derivarla a un flujo de manejo de errores.

¿Qué significa esto para tu startup?

El capital sigue mirando la automatización con apetito: Wonderful AI levantó US$550 millones a una valoración de US$5.000 millones para su plataforma de agentes de IA, según SiliconANGLE. Pero ninguna plataforma —ni la tuya ni la de tu proveedor— te protege de un cambio de versión mal gestionado. La diferencia entre un equipo que escala y uno que apaga incendios está en tratar la versión de cada API como una decisión de arquitectura, no como un detalle de implementación.

La buena noticia es que puedes separar lo que controla el proveedor de lo que controlas tú. No eliges si una API usa URL, encabezado, fecha o parámetro de consulta. Sí decides si tu integración depende del comportamiento por defecto del proveedor o si gestiona la versión de forma proactiva. Y esa segunda opción es la que evita que un martes cualquiera tu facturación, tu CRM o tu pipeline de datos empiecen a mover información incorrecta.

Dos acciones concretas para esta semana:

• Fija la versión explícitamente en cada integración crítica. En n8n, los nodos integrados gestionan el versionado por ti. Cuando no existe un nodo para el servicio, el HTTP Request node te permite hacer la versión parte de la configuración del workflow: la especificas en la URL, el encabezado o el parámetro, en lugar de heredar la versión por defecto del proveedor. Así el workflow sigue pidiendo la versión contra la que lo construiste y probaste.
• Convierte los avisos de deprecación en disparadores, no en correos que nadie lee. Inspecciona el status y los encabezados de la respuesta y busca una advertencia de deprecación o un 410 Gone. Una advertencia puede disparar una alerta o un workflow aparte que te dé tiempo para agendar la migración. Si la versión ya desapareció, corta el camino normal y envía el fallo a un Error Trigger node que inicie un proceso de recuperación; si ese proceso necesita parsing propio, añade código personalizado para normalizar o validar antes de decidir el siguiente paso.
• Automatiza el corte por fecha. Si el proveedor publica explícitamente la fecha de deprecación, un IF node te permite enrutar las peticiones según la fecha actual del servidor. Es la forma más barata de dejar de depender de la memoria de una persona.

Conclusión

El versionado de APIs deja de ser un problema cuando separas lo que el proveedor controla de lo que controlas tú. Tú no decides si una API versiona por URL, encabezado, fecha o query parameter, pero sí decides si tu integración se apoya en el valor por defecto o gestiona la versión de forma anticipada. Mantener esa lógica visible dentro del workflow —junto al resto del proceso, con sus rutas de error a la vista— es lo que convierte una migración forzada en una tarea planificada. Revisa hoy tus tres integraciones más críticas: si no sabes qué versión están usando ahora mismo, ese es el primer punto a resolver.

Fuentes

• API Versioning Strategies for Stable Workflow Integrations (fuente original)
• Wonderful raises $550M at $5B valuation for its AI automation platform