Aivorab
Ilustración editorial: Estrategias de Versionado de APIs: Una Guía Práctica para Equipos Pequeños

Diseño de API · versionado · REST · compatibilidad hacia atrás · Deprecación de API

Estrategias de Versionado de APIs: Una Guía Práctica para Equipos Pequeños

Una comparación técnica de las estrategias de versionado por ruta URL, encabezados y negociación de contenido, y cuándo aplica cada una para APIs pequeñas donde la compatibilidad hacia atrás importa.

Publicado:

El problema del versionado que realmente enfrentan los equipos pequeños

Toda API cambia. La pregunta no es si necesitarás versionado, sino cómo manejarlo sin convertir tu base de código en un cementerio de mantenimiento.

Para desarrolladores independientes y equipos pequeños, la presión por entregar rápido a menudo choca con la realidad de que los consumidores de la API no se actualizan según el calendario. Una librería cliente podría ir meses detrás. Un panel interno podría seguir llamando a tus endpoints de v1 mientras ya estás ejecutando v3. Tu trabajo es servir a ambos sin duplicar lógica en tres caminos de código.

Este artículo examina las tres estrategias principales de versionado—versionado por ruta URL, por encabezados y por negociación de contenido—y ofrece un marco práctico para elegir entre ellas.

Versionado por ruta URL: el predeterminado por una razón

El patrón está en todas partes: https://api.ejemplo.com/v1/usuarios, https://api.ejemplo.com/v2/usuarios.

Es el enfoque más común porque es el más inmediatamente comprensible. Cualquiera puede mirar una URL y saber qué versión está alcanzando. Probar en Postman no requiere encabezados especiales. La documentación es directa.

Pero el versionado por ruta URL conlleva costos reales.

Rompe la semántica REST. Una URI debería identificar un recurso. Cuando incrustas la versión en la ruta, estás tratando diferentes versiones como recursos diferentes en lugar de representaciones diferentes del mismo recurso. Esto no es solo académico—afecta cómo piensas en el diseño de tu API y cómo los clientes descubren los endpoints.

Fomenta la acumulación de código legado. Cada versión que agregas es una ruta que mantienes. Con el versionado basado en rutas, no hay un mecanismo natural para señalar que una versión está depreciada. Terminas con /v1/, /v2/, /v3/ ruteando a código activo, y la tentación de dejar las versiones antiguas corriendo “por si acaso” crece con cada lanzamiento.

Crea acoplamiento entre versión y estructura de endpoints. Si renombras un endpoint en v2, no puedes mantener la ruta v1. Los clientes que se rompen por un renombramiento no tienen una ruta de migración elegante—los has forzado a una nueva URL, lo cual es un cambio disruptivo sin importar si la forma de respuesta cambió.

Cuándo tiene sentido el versionado por ruta: APIs públicas donde la descubribilidad importa, APIs consumidas por partes no técnicas, o cuando necesitas que los clientes opten explícitamente por una versión porque los cambios disruptivos son frecuentes y significativos.

Versionado por encabezados: semántica más limpia, mayor fricción

El versionado por encabezados envía la información de versión en un encabezado HTTP en lugar de la URL. La forma más común es un encabezado personalizado:

Accept: application/vnd.ejemplo.v1+json

O un encabezado de versión dedicado:

X-API-Version: 1

La ventaja es la pureza semántica. La URI identifica el recurso. El encabezado identifica la representación. Esto se alinea con cómo fue diseñado HTTP—la negociación de contenido ha sido parte del protocolo desde RFC 2616. Estás usando la herramienta que el protocolo te da para exactamente este propósito.

La desventaja es la fricción. Los clientes necesitan conocimiento explícito de qué encabezado enviar. Depurar problemas de versión requiere inspeccionar encabezados de solicitud, no solo la URL. Algunas herramientas de middleware, CDNs y registro eliminan o ignoran encabezados personalizados, lo cual puede romper silenciosamente la resolución de versión.

El versionado por encabezados funciona mejor para bases de consumidor sofisticadas—otros equipos de ingeniería que entienden semántica HTTP, SDKs que pueden inyectar encabezados automáticamente, o APIs internas donde controlas ambos lados.

Negociación de contenido con tipos MIME propietarios

Este enfoque extiende el versionado por encabezados usando tipos de medios propietarios definidos en RFC 6838. En lugar de application/json, negocias application/vnd.crowbar.v2+json o application/vnd.crowbar.v2.3+json.

El esquema mayor.menor descrito por el Equipo SCC en SUSE es particularmente útil para APIs pequeñas. Las versiones menores indican cambios compatibles hacia atrás—nuevos campos, nuevos endpoints, parámetros opcionales. Las versiones mayores señalan cambios disruptivos. Esto te da un solo número de versión que comunica expectativas de compatibilidad sin requerir que los clientes analicen registros de cambios.

El compromiso es la complejidad. Los clientes deben entender la negociación de tipos MIME. Tu capa de ruteo debe analizar y coincidir con tipos propietarios. Algunos clientes HTTP usan application/json por defecto y no enviarán el tipo propietario a menos que se configure explícitamente. Necesitarás documentar el encabezado Accept correcto para cada endpoint.

Sin embargo, este enfoque tiene una ventaja estructural: mantiene el versionado ortogonal a tu diseño de URLs. Puedes reestructurar rutas, renombrar endpoints y agregar recursos sin tocar el esquema de versión. La versión vive en el tipo de contenido, no en la ruta.

El contraejemplo de GraphQL: versionado mediante evolución de esquema

GraphQL adopta una postura filosófica diferente. La guía oficial es clara: evita el versionado diseñando para evolución continua del esquema. Dado que los clientes solicitan solo los campos que necesitan, agregar un nuevo campo no rompe consultas existentes. Deprecar un campo a través de la directiva @deprecated permite a los consumidores migrar a su propio ritmo.

Esto funciona cuando controlas el esquema y tus consumidores usan un cliente tipado. Se rompe cuando tienes consumidores heterogéneos—algunos usando el esquema completo, otros usando clientes generados, otros consultando directamente. El modelo de deprecación requiere disciplina tanto de proveedores como de consumidores.

Para equipos pequeños, el enfoque de GraphQL vale la pena estudiarlo incluso si no lo adoptas. El principio—debes diseñar cambios para que sean aditivos en lugar de sustitutivos—se aplica a APIs REST también. Antes de versionar un endpoint, pregúntate si puedes agregar el cambio como un nuevo campo o endpoint en lugar de reemplazar el antiguo.

Una política de deprecación práctica

Independientemente de qué estrategia de versionado elijas, necesitas una política de deprecación. Sin ella, las versiones antiguas se acumulan indefinidamente.

Una política mínima para equipos pequeños:

  1. Anuncia la deprecación antes de eliminar. Da a los consumidores al menos un ciclo de lanzamiento mayor para migrar. Documenta la fecha de retiro en tu registro de cambios y en encabezados de respuesta (Sunset: <fecha>, Deprecation: <fecha>).

  2. Mantén solo las dos versiones mayores más recientes. Ejecutar tres o más versiones paralelas multiplica tu superficie de prueba sin valor proporcional. Si un consumidor está en v1 y v3 es la actual, debería migrar a través de v2.

  3. Devuelve encabezados de advertencia en endpoints depreciados. Un encabezado Warning: 999 "El endpoint /v1/usuarios está depreciado, usa /v2/usuarios en su lugar" da visibilidad programática a los clientes sin requerir que analicen documentación.

  4. Elimina las versiones depreciadas según un cronograma, no según una sensación. Seis meses es un mínimo razonable. Más tiempo y has creado deuda técnica. Menos tiempo y estás rompiendo clientes que legítimamente van detrás.

  5. Rastrea el uso. Si un endpoint depreciado tiene cero solicitudes en 90 días, es seguro eliminarlo. Si aún tiene tráfico, extiende la fecha de retiro y comunícate directamente con los consumidores.

Tomar la decisión

No existe una estrategia de versionado universalmente correcta. La elección adecuada depende de tus consumidores, tu frecuencia de cambios y tu tolerancia a la complejidad.

Elige versionado por ruta URL cuando:

Elige versionado por encabezados o negociación de contenido cuando:

Elige evolución de esquema estilo GraphQL cuando:

Para la mayoría de las APIs pequeñas, un híbrido pragmático funciona mejor: versionado por ruta para lanzamientos mayores con cambios disruptivos, y negociación de contenido para incrementos de versión menor. Esto te da la visibilidad de las URLs para cambios significativos mientras preservas la limpieza semántica para la evolución incremental.

El objetivo no es evitar el versionado. Es versionar de manera que la deprecación sea manejable y la migración predecible. Tu yo futuro—and tus consumidores—te lo agradecerán.

Preguntas frecuentes

¿Realmente necesito versionado si tengo cuidado con los cambios disruptivos?

Si nunca haces cambios disruptivos, no necesitas versionado. Pero “nunca” es un compromiso peligroso. Un tipo de campo cambiado, un parámetro opcional eliminado, o un arreglo de respuesta reordenado puede romper clientes de maneras que no anticipaste. El versionado es un seguro. La pregunta es cuánto seguro necesitas.

¿Puedo versionar a nivel de endpoint en lugar de a nivel de API?

Sí. Algunas APIs versionan endpoints individuales en lugar de toda la superficie. Esto es común en APIs grandes donde diferentes equipos poseen diferentes recursos. Para APIs pequeñas, el versionado a nivel de endpoint agrega complejidad sin beneficio proporcional. Versiona toda la API a menos que tengas una razón específica para no hacerlo.

¿Qué pasa con las claves de API y el versionado?

Las claves de API autentican consumidores; no seleccionan versiones. Mantén estos conceptos separados. Un consumidor podría tener una sola clave que accede a endpoints tanto de v1 como de v2. La selección de versión debe ocurrir a través de la solicitud (URL o encabezado), no a través de las credenciales.

¿Cómo manejo el versionado en la documentación OpenAPI/Swagger?

Documenta cada endpoint versionado por separado. Si usas versionado por ruta, incluye el segmento de versión en la definición de ruta. Si usas negociación de contenido, documenta el encabezado Accept esperado en la sección de encabezados de solicitud. No intentes documentar todas las versiones en un solo archivo de especificación—eso es una receta para la confusión.

Fuentes