Versionado de API

Existen tres enfoques principales. El versionado por URI (/v1/, /v2/) es el más común: los clientes especifican explícitamente la versión en cada URL de solicitud. Es simple y muy visible, pero las rutas que el equipo debe mantener en paralelo crecen con cada versión principal. El versionado por encabezado (API-Version: 2024-01-01) mantiene la URL limpia y permite el versionado basado en fechas (el modelo de Stripe), donde cada versión de API se nombra según una fecha y los clientes se actualizan a nuevos valores predeterminados en el aniversario de su cuenta. El versionado por parámetro de consulta (?version=2) es el más simple pero a menudo se considera el menos limpio. La mayoría de las API de SaaS utilizan el versionado por URI para las API públicas. Independientemente del mecanismo, los compromisos clave con los clientes son: ¿cuánto tiempo se admitirán las versiones antiguas? (el estándar de la industria es de 12 a 24 meses después del lanzamiento de una nueva versión); ¿cómo se definen y comunican los cambios disruptivos (breaking changes)? (una definición formal de "cambio disruptivo" evita debates durante la deprecación); y ¿cuál es la ruta de migración? (proporcionar guías de migración claras con ejemplos de código).

La deprecación de API es un evento de confianza del cliente; si se hace mal, genera un sentimiento negativo significativo incluso cuando la mejora del producto subyacente es positiva. Las mejores prácticas para la deprecación de API de SaaS: anunciar la deprecación con 12+ meses de anticipación (mínimo 6 meses para endpoints de bajo uso); proporcionar una fecha de finalización concreta (los plazos de deprecación ambiguos crean una falsa seguridad); enviar notificaciones dirigidas a cada cliente que utilice activamente el endpoint obsoleto (identificable a partir de los registros de API — "Estimado/a [Empresa], nuestros registros muestran que está llamando a /v1/users — este endpoint dejará de funcionar el [fecha]. Así es como puede migrar:"); publicar una guía de migración detallada con ejemplos de código antes/después; ofrecer un modo de compatibilidad o un período de adaptación donde la nueva versión se traduzca del esquema antiguo; y crear un panel de uso de endpoints obsoletos visible para los clientes en su configuración de administración, mostrando su uso y el tiempo restante.

Las deprecaciones de API generan de manera confiable aumentos en los tickets de soporte: los clientes migran en el último minuto, surgen problemas de integración y algunos clientes pasan por alto la deprecación por completo. Estrategias de mitigación: finalizar en oleadas en lugar de todo a la vez (deshabilitar para un 5% de clientes afectados seleccionados al azar dos semanas antes de la finalización completa, para que los problemas surjan con un volumen manejable antes del impacto total); aumentar el personal de soporte para la ventana de deprecación (programar horas adicionales de agentes en las dos semanas anteriores y posteriores a la fecha de finalización); pre-construir una macro de Zendesk con la guía de migración y soluciones de errores comunes, permitiendo una resolución rápida en el primer contacto por parte de los agentes de Nivel 1 sin escalada de ingeniería; crear una vista dedicada de Zendesk "Migración de API" para que estos tickets sean clasificados por sus agentes más capacitados técnicamente; y publicar una actualización de estado en tiempo real en su página de estado de desarrollador para el día de la finalización, con monitoreo de picos de errores relacionados con la migración.