Definicion
Cuando una API necesita evolucionar e introducir cambios incompatibles, ¿cómo permites que los clientes antiguos sigan funcionando mientras los nuevos obtienen nuevas características? El versionado por ruta URI es la respuesta más directa: poner el número de versión directamente en la URL donde todos puedan verlo. En lugar de /api/users, tienes /api/v1/users o /api/v2/users. Simple, explícito, imposible de pasar por alto.
Este enfoque se ha convertido en la estrategia de versionado más popular para APIs públicas, y con buena razón. Cuando un desarrollador mira la documentación de la API o inspecciona peticiones de red, la versión es inmediatamente visible. No hay que buscar en headers o tipos de contenido - la versión está ahí mismo en la URL. Esta explicitud hace que la incorporación sea más fácil, el debugging más simple, y la evolución de la API más clara.
La desventaja es que los puristas argumentan que las URLs deberían identificar recursos, no versiones - /users/123 es el usuario, independientemente de la versión de API. Pero en la práctica, diferentes versiones de API frecuentemente devuelven diferentes representaciones de recursos, así que la distinción en URL tiene sentido. Twitter, GitHub, Stripe y la mayoría de APIs importantes usan versionado por ruta porque sus beneficios - claridad, cacheabilidad y simplicidad - superan la impureza teórica.
Ejemplo
API de Twitter: Twitter usa /2/tweets para su API v2, mientras el antiguo /1.1/statuses/show.json servía v1.1. Los desarrolladores pueden ver claramente qué versión usa su código.
API de GitHub: La API REST de GitHub usa versionado por ruta implícitamente a través de diferentes URLs base y explícitamente en headers, pero su API GraphQL usa un endpoint estable. El enfoque híbrido muestra cómo diferentes necesidades llevan a diferentes estrategias.
API de Stripe: Stripe usa versionado basado en fechas en headers pero mantiene rutas URL estables. Cuando introdujeron v2 de recursos específicos, usaron prefijos de ruta claros.
APIs de Google: Muchas APIs de Google usan versionado por ruta como /v1/projects o /v2/files, dejando inmediatamente claro con qué versión te estás integrando.
Analogia
Los Pisos del Edificio: Imagina un edificio de oficinas donde diferentes versiones de una empresa ocupan diferentes pisos. Marketing v1 está en el piso 1, Marketing v2 con la nueva estructura de equipo está en el piso 2. Cuando necesitas servicios de marketing, sabes exactamente qué piso visitar basándote en qué “versión” necesitas. El versionado por ruta URI pone versiones de API en diferentes “pisos” de la URL.
Los Departamentos de la Tienda: Una tienda departamental podría reorganizarse con el tiempo. El antiguo layout de electrónicos está en el “ala A,” el nuevo layout está en el “ala B.” Los carteles te dirigen claramente. El versionado URI pone señales claras en la URL.
Las Salidas de Autopista: Las autopistas tienen salidas numeradas que no cambian una vez establecidas. Los nuevos destinos obtienen nuevos números de salida en lugar de renombrar los antiguos. Las versiones por ruta de API funcionan de manera similar - v1 se queda como v1, y las nuevas características obtienen v2.
Las Ediciones de Libros: Las librerías tienen diferentes ediciones de libros de texto. El estante de “5ta edición” está separado del estante de “6ta edición.” Los estudiantes saben exactamente cuál comprar. El versionado URI coloca versiones de API por separado.
Code Example
// [Versionado](https://reference.apios.info/es/terms/versioning/) por ruta URI
GET https://api.company.com/v1/customers/123
GET https://api.company.com/v2/customers/123
GET https://api.company.com/v3/customers/123
// También puede usar major.minor
GET https://api.company.com/v2.1/customers/123
// Respuesta v1 (simple)
{
"id": 123,
"name": "ACME Corp"
}
// Respuesta v2 (mejorada)
{
"id": 123,
"name": "ACME Corp",
"tier": "enterprise",
"createdAt": "2024-01-15T10:00:00Z"
}