Versionado de API para productos en etapa temprana: patrones pragmáticos

Por qué el versionado duele más cuando te mueves rápido

La velocidad es buena hasta que un pequeño cambio en la API rompe algo que no controlas. Un campo renombrado, un nuevo parámetro obligatorio o un formato de error distinto pueden tumbar silenciosamente apps móviles, integraciones con socios y scripts que alguien ejecuta cada mañana.

El problema real no es tanto el cambio en sí. Es la brecha entre cuando lo despliegas y cuando cada cliente se actualiza. Las aplicaciones web pueden enviar correcciones rápido. Las apps móviles pueden esperar días o semanas por una publicación en la tienda. Los socios pueden actualizar en ciclos trimestrales. Y los scripts y automatizaciones pueden nunca tocarse de nuevo porque a nadie le importa que existan.

También ayuda ser claro sobre qué cuenta como “cliente”. Es más que “usuarios externos”. Los clientes suelen incluir tus apps web y móviles, integraciones con socios y clientes, servicios internos y jobs en segundo plano, automatizaciones (scripts cron, macros de hojas de cálculo, flujos tipo Zapier) e incluso suites de pruebas o herramientas de monitorización que llaman a la API.

Por eso el versionado puede resultar doloroso para productos en etapa temprana. Intentas moverte rápido, pero también necesitas que los clientes antiguos sigan funcionando el tiempo suficiente para que la gente se ponga al día. El objetivo no es congelar tu API para siempre. Es ganar tiempo y reducir sorpresas.

Una mentalidad pragmática es: lanzar cambios compatibles con versiones anteriores por defecto, y tratar los cambios incompatibles como un lanzamiento planificado, no como un parche rápido. Eso significa que necesitas una forma de ejecutar comportamiento antiguo y nuevo en paralelo, un plan de despliegue y mensajes simples que digan qué cambia, cuándo cambia y qué deben hacer los clientes.

Qué suele obligar a cambiar un endpoint

La mayoría de los endpoints no cambian porque a alguien le apetezca refactorizar. Cambian porque el producto cambia. Los equipos en etapa temprana aprenden más rápido de lo que su contrato de API puede seguir, y la primera versión a menudo refleja las tablas de la base de datos de hoy en lugar de una promesa estable para los clientes.

Algunos cambios son aditivos y por lo general seguros. Otros son incompatibles y sorprenderán a los clientes en producción. La parte complicada es que ambos pueden parecer pequeños en el código, pero enormes para cualquiera que integre tu API.

Razones comunes por las que los equipos cambian un endpoint

Los campos de respuesta y las formas son uno de los grandes puntos. Puedes renombrar userId a id, dividir name en firstName y lastName, o convertir una cadena en un objeto porque “ahora necesitamos más campos”. Esos son cambios incompatibles para cualquier cliente que analice las respuestas estrictamente.

Los cambios de autenticación también obligan a actualizar endpoints. Pasar de API keys a OAuth, añadir scopes obligatorios o cambiar cómo se envían los tokens (cabecera vs cookie) puede romper clientes aunque la ruta del endpoint siga igual.

La paginación es otro habitual. Pasar de “devolver todo” a limit/offset, cambiar a paginación por cursor o modificar la ordenación por defecto afecta lo que los clientes ven y cómo piden más datos.

Los formatos de error evolucionan también. Las APIs tempranas a menudo devuelven formas inconsistentes (a veces una cadena, a veces JSON). Más adelante quieres una estructura estándar con códigos y detalles. Es una mejora real, pero puede romper clientes que comparan con mensajes antiguos.

Aditivo vs incompatible: un modelo mental rápido

Los cambios aditivos suelen ser seguros cuando los clientes ignoran lo que no entienden: añadir campos de respuesta opcionales, nuevos endpoints, aceptar nuevos campos de solicitud opcionales y (a veces) añadir valores de enum nuevos si los clientes manejan valores desconocidos.

Los cambios incompatibles requieren un plan porque los clientes existentes pueden fallar de inmediato: renombrar o eliminar campos, cambiar campos obligatorios o reglas de validación, modificar requisitos de autenticación o manejo de tokens, cambiar comportamiento de paginación o estructura de respuesta, y cambiar códigos de estado o formato del cuerpo de error.

Los productos tempranos están más en riesgo porque el modelo de datos se mueve, las pruebas son débiles y el “contrato” vive en la cabeza de alguien o en un hilo de Slack. Un contrato estable significa que decides qué promete la API (campos, tipos, comportamientos, errores) y cumples esa promesa mientras el código interno y la base de datos siguen evolucionando.

Elige un esquema de versionado que realmente puedas mantener

El mejor esquema de versionado es el que tu equipo seguirá cada vez, incluso en un día ocupado. Si requiere muchos casos especiales, se saltará y los clientes lo pagarán.

Versionado por ruta: simple y obvio

Con el versionado en la ruta pones la versión en la ruta URL, como /v1/orders y /v2/orders. Para productos en etapa temprana, esto suele ser lo más fácil de entender para clientes externos, QA, soporte y cualquiera que lea logs. También deja claro a qué documentación y ejemplos aplica cada versión.

No es perfecto (puede que termines versionando cosas que no necesitaban cambiar), pero la simplicidad es la idea. Menos sorpresas cuando te mueves rápido.

Versionado por cabeceras y parámetros de consulta: potente, pero más fácil de liarla

El versionado por cabecera manda la versión en una cabecera de petición (por ejemplo, un Accept-style header). El versionado por parámetro usa algo como ?version=2. Ambos pueden funcionar, pero añaden fricción: la versión es más difícil de notar en logs y capturas de pantalla, depurar problemas de cliente lleva más tiempo, algunos proxies/caches/herramientas gestionan mal cabeceras personalizadas y algunos equipos clientes olvidan establecer la cabecera de forma consistente.

El versionado por tipo de medio (media-type versioning), una variante del versionado por cabecera, puede ser elegante, pero es otra pieza móvil que explicar y aplicar, especialmente si ya estás lidiando con diferencias de autenticación, caché y comportamiento de SDKs.

Una regla práctica para equipos pequeños: si la mayoría de los clientes viven fuera de tu repo (socios, agencias, apps móviles gestionadas por otro equipo), el versionado por ruta suele ser lo menos confuso.

Sea cual sea tu elección, elige un enfoque y mantente con él en toda la API. Mezclar /v1 en algunos sitios, cabeceras en otros y parámetros en un endpoint aislado hace que la documentación sea menos fiable y aumenta la carga de soporte.

Predetermina la compatibilidad hacia atrás cuando puedas

Moverse rápido no tiene por qué significar romper clientes. La mayoría del dolor de API temprano viene de pequeños cambios que obligan a todos los consumidores a actualizar al mismo tiempo. Si puedes mantener a los clientes antiguos funcionando, ganas tiempo para mejorar el diseño sin convertir cada lanzamiento en una emergencia.

El valor por defecto más seguro son los cambios aditivos: añade cosas sin quitar nada. Eso suele significar añadir un campo opcional, un nuevo filtro que limite resultados o un endpoint nuevo para un flujo distinto. Los clientes antiguos siguen enviando las mismas peticiones y reciben respuestas que entienden.

Cuando necesites evolucionar una respuesta, prefiere extenderla. Añade campos nuevos como opcionales y deja los antiguos sin cambios. Añade parámetros de consulta nuevos que por defecto mantengan el comportamiento actual. Si un nuevo flujo no encaja bien, añade un endpoint nuevo en lugar de sobrecargar el antiguo.

Un error común es cambiar el significado de un campo existente porque el nombre es conveniente. Por ejemplo, empiezas con status: "active" | "inactive", luego reutilizas inactive para significar “pausado por facturación”. Parece pequeño, pero rompe la lógica de negocio de formas silenciosas y costosas. Si el concepto cambia, introduce un campo nuevo o un nuevo valor enum con nombre claro y mantén el significado antiguo estable hasta que puedas retirarlo.

El análisis tolerante es la otra mitad de la compatibilidad hacia atrás. En el lado del cliente, la regla es simple: ignora lo que no reconoces. Si el servidor añade marketingConsent o shippingEta, los clientes antiguos no deberían fallar porque apareció JSON adicional. Si publicas SDKs, asegúrate de que no rechacen campos desconocidos por defecto.

Mantén estables las formas de error

Los clientes dependen de los formatos de error más de lo que esperas. Cambiar respuestas de éxito es visible, pero cambiar errores de validación puede romper formularios, flujos de onboarding y lógica de reintentos.

Intenta mantener estables:

• Los nombres de los códigos de error (o códigos numéricos) y su significado
• La forma general de la respuesta de error (claves de nivel superior, anidamiento)
• La estructura de errores de validación (ruta del campo, mensaje, tipo)

Si hoy la validación devuelve { "error": { "code": "INVALID_EMAIL", "field": "email" } }, no pases a { "errors": [ ... ] } sin un plan de compatibilidad. Si debes mejorarla, añade una clave nueva y mantén la antigua por un tiempo.

Los cambios compatibles no siempre son posibles, pero lo son con más frecuencia de lo que los equipos suponen. Trata los cambios incompatibles como último recurso y lanzarás más rápido en general porque no estarás constantemente esperando a que los clientes se actualicen.

Cómo ejecutar dos versiones sin duplicar trabajo

Ejecutar v1 y v2 en paralelo suele ser lo más seguro, especialmente cuando los clientes actualizan despacio y no puedes permitirte sorpresas. El objetivo es simple: mantener v1 estable para usuarios existentes mientras pruebas v2 con tráfico real.

Un enfoque práctico es mantener ambas versiones en vivo, pero evitar mantener dos pilas de lógica de negocio separadas. Trata v2 como la implementación real y haz de v1 una capa delgada de compatibilidad.

Usa una capa de traducción (cuando sea realista)

Si las formas están próximas, puedes traducir internamente las peticiones v1 a v2. v1 sigue disponible, pero la mayor parte del flujo de código es compartida.

Traducciones que suelen merecer la pena:

• Mapear campos renombrados (por ejemplo, userId a account_id) y rellenar valores por defecto sensatos.
• Convertir enums antiguos a valores nuevos, y rechazar solo los casos realmente imposibles.
• Transformar respuestas v2 de vuelta al formato v1 para que los clientes antiguos no tengan que cambiar.

Esto mantiene las correcciones y parches de seguridad en un solo lugar y evita “dos bugs por el precio de uno”.

Prueba v2 de forma segura con enrutamiento y flags

Puedes desplazar tráfico gradualmente sin obligar a los clientes a elegir una versión el primer día. Los patrones comunes incluyen permitir que una cabecera opte por v2, enrutar un pequeño porcentaje de peticiones a v2 o habilitar v2 solo para cuentas internas primero. Si algo va mal, reviertes la regla de enrutamiento, no todo el despliegue.

Para mantener la ejecución paralela honesta, decide desde el principio qué significa “bien” y vigila un pequeño conjunto de métricas: tasa de errores por versión y endpoint, latencia (p50 y p95) por versión, adopción (cuántos clientes llaman v2) y con qué frecuencia v1 necesita traducción especial.

Despliegue paso a paso para un cambio incompatibile

Los cambios incompatibles se sienten riesgosos porque crean dos problemas a la vez: tu servidor puede fallar y los clientes pueden romperse en silencio.

Empieza escribiendo el cambio como una corta “historia para el cliente” en lenguaje llano. Nombra exactamente qué debe hacer el cliente de forma distinta. Por ejemplo: “/orders ahora devuelve totalCents en lugar de total, y status puede ser backordered.” Si no puedes explicarlo en cinco frases, no estás listo para lanzarlo.

Luego añade el nuevo comportamiento detrás de un interruptor claro: una ruta versionada, una cabecera de versión o una feature flag para IDs de cliente específicos. Elige uno y mantenlo aburrido. El objetivo es ejecutar comportamiento antiguo y nuevo en paralelo.

Una secuencia de despliegue que te mantiene en control:

• Describe el nuevo contrato y los pasos de migración, incluidos ejemplos de petición/respuesta.
• Implementa la nueva versión detrás de un interruptor y mantén v1 sin cambios.
• Lanza v2 con logging que registre qué versión usó cada petición (y qué clientes siguen en v1).
• Anuncia la deprecación con una fecha firme, más una guía de migración corta y una forma de hacer preguntas.
• Vigila la adopción, arregla los bloqueadores reales y luego apaga v1 por fases (advertir, limitar y luego eliminar).

El logging es donde los equipos suelen ganar o perder. Si no puedes responder “¿quién sigue llamando v1?”, estás adivinando. Si heredaste un backend sin enrutado claro o métricas, arregla eso primero o te costará retirar versiones de forma segura.

Cuando llegue la hora de retirar, hazlo con cuidado: devuelve mensajes de error claros, mantén una respuesta temporal de “cómo migrar” y documenta el reemplazo exacto para que los clientes se recuperen rápido.

Cómo comunicar desaprobaciones para que la gente confíe en ti

Las desaprobaciones van principalmente de expectativas. Si la gente se entera de un cambio después de que su app se rompe, dejan de confiar en tu API. Si lo ven venir, con pasos claros, la mayoría se adaptará sin drama.

Elige un pequeño conjunto de señales y úsalas de forma consistente. Para equipos pequeños, hacer pocas cosas de forma fiable vence a anunciar cambios en cinco sitios y olvidar dos.

Señales que funcionan bien:

• Cabeceras de respuesta en los endpoints afectados
• Un changelog corto o una nota de release
• Email a desarrolladores o clientes conocidos que usan el endpoint
• Una notificación en producto o banner en el dashboard (si lo tienes)

Sé específico sobre lo que se depreca. “v1 se va a ir” es demasiado vago si solo un endpoint cambia. Señala las desaprobaciones parciales claramente: un único endpoint, un campo en la respuesta o un comportamiento como la ordenación por defecto. También di qué queda igual, para que la gente no pierda tiempo reescribiendo código que no se ve afectado.

Los plazos deben ser realistas. Los productos que se mueven rápido todavía deben dar tiempo a los usuarios. Una ventana práctica suele ser de 1 a 3 semanas para un cambio incompatible, con plazos más cortos solo cuando el problema es urgente (por ejemplo, un problema de seguridad). Si realmente solo puedes dar días, dilo claramente y ofrece ayuda para migrar.

Una plantilla de mensaje simple mantiene tus actualizaciones fáciles de leer:

• Qué cambia (endpoint, campo o comportamiento) con un ejemplo
• Cuándo (fecha de deprecación y fecha en que dejará de funcionar)
• Cómo migrar (el cambio mínimo de código)
• Dónde preguntar (un canal de soporte y qué información incluir)

Ejemplo: “El campo user.name será eliminado el 10 de feb. Usa user.display_name en su lugar. Ambos están disponibles hasta entonces.” Es corto, comprobable y difícil de malinterpretar.

Trampas comunes que rompen clientes (y tu calendario)

La mayoría de las roturas de API no son dramáticas. Son decisiones pequeñas que parecieron razonables en el momento y luego se convierten en tickets de soporte, hotfixes y correos incómodos.

Trampa 1: versionar demasiado pronto

Si creas v1, v2, v3 antes de tener presión real de clientes, te atas a mantener decisiones antiguas. Los productos en etapa temprana cambian rápido y cada versión extra multiplica la superficie que tienes que probar.

Una regla simple: no crees una nueva versión solo para mantener las cosas ordenadas. Hazlo cuando realmente no puedas mantener el comportamiento actual para los clientes existentes.

Trampa 2: versionar demasiado tarde

Lo contrario duele más: lanzas un cambio incompatible sin una ruta de migración. Puede parecer más rápido, pero lo pagarás cuando la app de alguien o una integración de un socio deje de funcionar.

Si debes romper algo, mantén el comportamiento antiguo disponible el tiempo suficiente para que los clientes se muevan. Incluso una superposición corta es mejor que nada.

Trampa 3: mezclar estrategias de versionado

Algunos equipos ponen versiones en la URL para ciertos endpoints, usan cabeceras para otros y cambian formas de petición/respuesta en otros sitios sin avisar. Los clientes acaban adivinando qué regla aplicar.

Elige un esquema principal y aplícalo de forma consistente. Si necesitas un segundo mecanismo (por ejemplo, una cabecera temporal), trátalo como una excepción de corta duración y documéntalo claramente.

Trampa 4: cambios silenciosos de comportamiento

Los peores bugs pasan cuando la misma petición empieza a significar algo diferente. Quizá un campo pasa a ser opcional pero ahora tiene un valor por defecto distinto. Quizá un filtro cambia de lógica AND a OR. Nada “rompe” a nivel HTTP, pero los resultados están mal y es difícil detectarlo.

Antes de lanzar, escribe: para esta petición exacta, ¿qué respuesta deberían esperar los clientes? Si el significado cambia, trátalo como un cambio incompatible, incluso si el esquema parece igual.

Trampa 5: sin observabilidad sobre versiones

Si no puedes decir quién sigue en v1, no puedes deprecar con seguridad. Construye una vista básica del uso de versiones, aunque sea simple.

Un enfoque ligero:

• Registra la versión usada en cada petición (ruta o cabecera)
• Rastrea los principales clientes que siguen llamando versiones antiguas
• Vigila tasas de error por versión por separado
• Ponte una fecha interna para revisar uso y decidir los siguientes pasos

Lista de comprobación rápida antes de lanzar un cambio incompatible

Los cambios incompatibles se ven pequeños en tu editor y enormes en la app de otra persona. Antes de empujar algo que pueda romper clientes, haz un repaso rápido con la misma mentalidad que usarías para un outage: “¿Qué fallará primero y cómo lo notaremos?”

Compatibilidad y comportamiento

Empieza probando que el cliente antiguo todavía puede hacer lo básico. No asumas que funciona porque las peticiones devuelven 200.

• Confirma que un cliente v1 pueda autenticarse y completar los flujos principales (las 2 o 3 peticiones que mantienen el producto usable).
• Mantén las formas de respuesta estables: añade campos nuevos como opcionales y no cambies significados de campos existentes.
• Revisa también respuestas de error (códigos de estado y formato de error).
• Verifica valores por defecto: si introduces un campo obligatorio en v2, asegúrate de que v1 siga teniendo un valor por defecto seguro.
• Ejecuta al menos un cliente real (móvil/web/socio) contra staging, no solo pruebas unitarias o un script curl.

Observabilidad, comunicaciones y redes de seguridad

Asegúrate de poder ver quién se verá afectado y guiarles con claridad.

• Registra el identificador del cliente y la versión en cada petición para poder nombrar a los principales llamadores y sus endpoints.
• Redacta un aviso de deprecación con fecha, endpoints exactos, qué cambia y un resumen corto de migración.
• Prepara una ruta de rollback: una feature flag, una regla en el gateway o la capacidad de enrutar tráfico de vuelta a v1 rápidamente.
• Decide qué significa “terminado” para la deprecación (por ejemplo: menos del 1% del tráfico en v1 durante 14 días).
• Configura una alerta para errores v2 que importen a los usuarios (fallos de auth, picos de 5xx, saltos de latencia).

Un chequeo final simple: si v2 empieza a generar incidentes en la primera hora, ¿puedes reducir el daño en cinco minutos sin redeploy? Si la respuesta es no, añade el gancho de seguridad primero.

Ejemplo: cambiar un endpoint central sin romper tu app móvil

Un cambio común en etapas tempranas: empezaste con /users, pero el negocio cambia y en realidad son clientes que pagan. Quieres renombrar el recurso a /customers. Al mismo tiempo quieres cambiar la paginación de page y per_page a un cursor cursor y limit porque funciona mejor en móvil.

Si “simplemente lo cambias”, la app en la tienda seguirá llamando al endpoint antiguo durante días o semanas. Eso convierte un refactor ordenado en tickets de soporte y parches de emergencia.

Un plan seguro que mantiene la app funcionando

Trátalo como un cambio aditivo. Mantén el contrato antiguo, introduce el nuevo y cómprate tiempo.

• Añade /v2/customers con el nuevo nombre y paginación por cursor.
• Mantén /v1/users funcionando exactamente como antes.
• Si puedes, traduce las peticiones internamente para que ambos endpoints compartan la misma lógica subyacente.
• Añade cabeceras de respuesta o logs que te digan qué clientes siguen usando /v1/users.
• Actualiza la app móvil para usar /v2/customers, pero mantén una opción de fallback a /v1/users durante la transición.

Una línea temporal de deprecación simple que la gente puede seguir

Publica un cronograma claro y repítelo donde los desarrolladores realmente lo verán.

• Día 0: Anuncia la deprecación de /v1/users. Proporciona un ejemplo de petición/respuesta para /v2/customers.
• Día 14: Recordatorio con estadísticas de uso (por ejemplo: “3 clientes siguen llamando /v1/users”).
• Día 30: Congela /v1/users (no nuevos campos, no cambios de comportamiento). Mantén su estabilidad.
• Día 60: Retira /v1/users con un mensaje de error predecible que apunte al reemplazo.

Vigila el tráfico mientras avanzas. Si una parte significativa de usuarios reales sigue en la versión antigua, extiende la ventana en vez de romperles.

Siguientes pasos: inventaría tus endpoints actuales, lista qué rompería clientes (rutas, nombres de campos, paginación, códigos de estado) y escribe un plan de migración de una página antes de tocar el código. Si heredaste una base de código generada por IA que sigue rompiéndose cuando cambias endpoints, FixMyMess (fixmymess.ai) puede ayudar auditando el código, reparando las partes riesgosas y preparando una ruta de despliegue de v2 más segura sin forzar a cada cliente a actualizar de la noche a la mañana.