Versionado de API que sobrevive tres años

Año uno: REST API limpia, prefijo /v1, docs swagger. Año dos: app mobile, tres partners de integración, herramientas admin internas. Año tres: un rename de campo breaking shippea en un deploy de viernes. Webhooks de partners fallan en silencio. Clientes mobile en builds viejos crashean al parsear. Nadie sabe qué consumidores siguen llamando al endpoint deprecado porque el logging no capturaba client identity. Una estrategia de versionado de API que sobrevive tres años no es sintaxis — es política: qué puede cambiar sin aviso, qué exige nueva versión, cuánto viven las versiones viejas y cómo se mide el sunset — no se adivina.

Las APIs son contratos más largos que la mayoría de los codebases. Clientes externos actualizan en sus calendarios, no en el tuyo. Apps mobile quedan en app stores por meses. Integraciones enterprise requieren trimestres de aviso. Servicios internos se multiplican sin que nadie lo note. El versionado es cómo los equipos cambian APIs en producción sin pretender que todo consumidor deploya simultáneamente.

Versionar lo que rompe; expandir lo que no

Change type	Strategy	Example
Agregar campo opcional	Sin version bump	Nuevo campo JSON, ignorado por clientes viejos
Agregar endpoint opcional	Sin version bump	Nueva ruta, rutas viejas sin cambios
Renombrar campo	Breaking — versión o alias	user_name → display_name con período de dual-write
Eliminar campo	Breaking — versión + sunset	Deprecation header, telemetría, luego removal
Cambiar semántica	Breaking — versión	status: "active" ahora excluye trial
Cambiar auth	Breaking — versión	Cambios de OAuth scope, cambios de formato de key
Solo performance	Usualmente no versionado	Respuesta más rápida, misma shape

Los cambios aditivos son el default. Los breaking changes exigen incremento de versión O capa de compatibilidad con sunset documentado.

/v2 en la URL no es estrategia de versionado. Es una etiqueta. La política es la estrategia.

El patrón strangler fig legacy migration aplica a APIs — enrutar tráfico a implementaciones nuevas detrás de una fachada mientras la versión vieja decae con tráfico medido, no fechas arbitrarias.

Estilos de versionado y tradeoffs

URL path (/v1/users). Visible, fácil de enrutar en gateway. Riesgo: clientes hardcodean path; proliferan URLs de recursos.

Header (Accept: application/vnd.company.v2+json). URLs limpias. Riesgo: más difícil de testear en browser; clientes olvidan el header.

Query param (?api-version=2024-01-01). Claridad basada en fecha. Riesgo: errores de caching; params eliminados por proxies.

Content negotiation. Conforme a estándares. Riesgo: complejidad; soporte inconsistente en clientes.

Elegir un estilo primario por superficie de API. Mezclar estilos entre endpoints confunde consumidores y observabilidad. Documentar la elección donde aterrizan primero los integradores — developer portal, banner en OpenAPI spec, mensajes de error en llamadas deprecadas.

Versiones basadas en fecha (2024-06-01) comunican timelines de sunset mejor que enteros opacos (v3). Los enteros sirven internamente si el changelog mapea integer → date → deprecation policy.

Deprecation es un producto con telemetría

Sunset sin datos de uso es vandalismo contra integradores.

Deprecation headers en cada respuesta de versión vieja:

Deprecation: true
Sunset: Sat, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.example.com/migration/v1-to-v2>; rel="successor-version"

Métricas por cliente/versión:

• Requests por versión de API por día
• Client IDs únicos o API keys por versión
• Error rates en campos deprecados
• Versión de cliente activa más antigua

Política de sunset escrita de antemano:

• Período mínimo de aviso (90 días consumer, 180 días enterprise — ajustar a contratos)
• Outreach activo cuando client ID sigue en versión deprecada a T-60 días
• Hard sunset solo cuando tráfico bajo umbral O aviso contractual completo

Nunca eliminar una versión que la telemetría muestra con integraciones activas de pago sin sign-off de owner nombrado.

Patrones de compatibilidad que retrasan forks de versión

Antes de crear /v2, agotar compatibilidad:

Field aliasing. Devolver user_name y display_name durante la transición. Write acepta ambos. Eliminar alias tras sunset.

Default values para campos required nuevos. El server provee default sensato cuando clientes viejos omiten el campo — documentar en changelog.

Response shaping por versión. Gateway o capa handler mapea modelo interno a shape v1 o v2 — acumula mapping debt pero evita doble implementación.

Feature flags para cambios de comportamiento. Mismo endpoint, flag controla semántica nueva — útil para clientes internos; APIs externas prefieren versiones explícitas.

Las capas de mapping se acumulan. Rastrear mapping debt — cuando el mantenimiento de alias supera el costo de nueva versión, forkear versión y sunsetear v1 en calendario.

Documentación y changelog como infraestructura de versionado

Los integradores leen changelogs, no commit history.

• Breaking change log — fecha, endpoints afectados, pasos de migración, fecha de sunset.
• OpenAPI por versión — specs separados o spec único versionado con tags claros.
• Migration guides — code samples para los lenguajes principales de clientes, no solo prosa.
• Webhook versioning — topic separado o campo payload version; partners pierden versionado por URL.

OAuth scopes y diseño de autorización intersecta con versionado — cambios de scope son breaking para clientes con tokens viejos. Versionar requisitos de auth explícitamente en changelog.

¿Cómo deben diseñar los equipos versionado de API a largo plazo?

Estas políticas previenen version sprawl y breakages sorpresa.

¿Cuántas versiones activas deben correr simultáneamente?

Típicamente dos — actual y anterior. Tres crea triple carga de mantenimiento. Excepción: contratos enterprise que exigen soporte extendido — cobrarlo o documentarlo como costo ligado a revenue.

¿Cuándo es obligatoria una nueva versión major?

Cuando el costo de capa de compatibilidad supera el fork, cuando el cambio semántico no puede aliasearse, o cuando seguridad exige romper auth vieja. No cuando un rename se vería más limpio — la limpieza no es criterio de breaking change.

¿Cómo afectan los clientes mobile los timelines de sunset?

Mobile va meses detrás del server — app store review, tasas de update de usuarios. La política de sunset debe exceder la cola mobile; feature flags server-driven no arreglan parse errors de binarios viejos. Mantener shapes de respuesta viejos hasta que analytics muestren tráfico negligible de versiones viejas de app.

Un argumento común va en la dirección opuesta

La visión opuesta sostiene que versionado estricto frena innovación — que los equipos deberían shippear breaking changes rápido y esperar que clientes sigan el ritmo.

Los clientes que pagan facturas no siguen el cadence del sprint. Romper APIs sin versionado transfiere velocidad de ingeniería a customer support y churn. Política additive-first con breaks versionados raros es más rápida neto — menos fire drills, menos llamadas de emergencia a partners.

GraphQL y patrones BFF desplazan dónde vive el versionado pero no eliminan disciplina de contrato — reglas de schema deprecation aplican igual.

Key takeaways

• Versionar solo breaking changes — campos y endpoints aditivos no necesitan version bump.
• Elegir un estilo de versionado; documentar política de sunset antes de shippear v1.
• Deprecation headers, telemetría por cliente/versión y períodos mínimos de aviso son obligatorios.
• Field aliasing y response shaping retrasan forks — rastrear mapping debt.
• Clientes mobile y enterprise extienden timelines de sunset — medir, no adivinar.
• Changelog y migration guides son infraestructura de versionado, no afterthoughts.

Conclusion

El versionado de API que sobrevive tres años se mide en política y telemetría, no en prefijos de path. Equipos que registran uso de versión por cliente, deprecan con aviso y expanden antes de romper mantienen confianza con integradores que nunca conocerán. Equipos que rompen campos en deploys de viernes mantienen backlog de partners enojados.

La auditoría: listar versiones activas de API, volumen de requests por versión, cliente más viejo aún en cada una. Si alguna versión carece de fecha de sunset y métrica de tráfico, ese es el platform work de este trimestre.