Definición
Imagina que tienes una aplicación que funciona perfectamente con una API externa. Un día, el proveedor cambia el formato de respuesta y tu aplicación deja de funcionar. Frustrante, ¿verdad? El versionado de APIs existe precisamente para evitar esto - es como tener varias ediciones de un libro donde los lectores de ediciones anteriores pueden seguir leyendo mientras los nuevos disfrutan de contenido actualizado.
El versionado permite que una API evolucione sin romper las aplicaciones que ya dependen de ella. Cuando introduces un cambio que podría afectar a los clientes existentes - como cambiar el formato de una fecha o eliminar un campo - en lugar de modificar la API existente, creas una nueva versión. Los clientes antiguos siguen usando v1, los nuevos pueden adoptar v2 con las mejoras. Ambos coexisten felizmente.
¿Cómo se implementa? Hay varias estrategias: poner la versión en la URL (/v1/users, /v2/users), en un header HTTP (X-API-Version: 2), en parámetros de query (?version=2), o en el media type (Accept: application/vnd.myapi.v2+json). Cada enfoque tiene pros y contras, pero lo importante es elegir uno y ser consistente. Stripe, por ejemplo, usa fechas como versiones (2024-04-10) permitiendo a los comercios actualizar a su propio ritmo.
Ejemplo
Stripe y sus Versiones por Fecha: Stripe versiona su API con fechas. Cuando creas una cuenta, se te asigna la versión del momento. Si lanzan cambios el 2024-04-10, tu código sigue usando tu versión original a menos que explícitamente actualices. Esto te permite probar nuevas versiones en desarrollo antes de adoptar en producción.
Twitter/X API v1 vs v2: Twitter mantuvo su API v1 durante años mientras desarrollaba v2 con características completamente nuevas (como búsqueda mejorada y campos expandidos). Los desarrolladores pudieron migrar gradualmente, y Twitter eventualmente deprecó v1 dando meses de aviso.
Google Maps Platform: Google usa versiones en la URL (v3/places) y además soporta “weekly” y “quarterly” channels para testing. Puedes probar la próxima versión antes de que sea estable, permitiendo preparar tu código para cambios futuros.
Facebook Graph API: Facebook lanza nuevas versiones regularmente y mantiene las anteriores por aproximadamente 2 años. Cuando lanzaron Graph API v19.0, v17.0 y anteriores seguían funcionando. Esto da tiempo suficiente para que millones de apps migren sin presión.
Analogía
Las Ediciones de Libros de Texto: Un libro de matemáticas tiene 5ta, 6ta, 7ma edición. Los estudiantes con la 5ta edición pueden seguir estudiando perfectamente. La 7ma tiene ejercicios nuevos y correcciones, pero no invalida lo que aprendiste con la anterior. Los profesores pueden decidir cuándo adoptar la nueva edición.
Los Modelos de Coches por Año: Un Toyota Corolla 2020 y uno 2024 son el mismo “producto” pero con diferencias. Los repuestos del 2020 siguen existiendo, los mecánicos saben arreglar ambos. Toyota no descontinúa soporte al sacar un nuevo modelo - ambos coexisten en el mercado y en los talleres.
Las Versiones de Sistemas Operativos: Windows 10 y Windows 11 coexisten. Microsoft no te fuerza a actualizar inmediatamente. El software que funciona en Windows 10 sigue funcionando. Eventualmente Windows 10 dejará de tener soporte, pero con años de aviso para que migres.
Los Menús de Restaurante con “Clásicos”: Un restaurante actualiza su menú pero mantiene los “platos clásicos” que los clientes habituales esperan. Puedes probar los nuevos platos de temporada o quedarte con tu favorito de siempre. El chef evoluciona sin alienar a los clientes leales.
Code Example
// Múltiples estrategias de versionado
// 1. [Versionado](https://reference.apios.info/es/terms/versioning/) en la ruta URI (más común)
GET /v1/products
GET /v2/products
// 2. Parámetro de query
GET /products?version=2
// 3. Header personalizado
GET /products
X-API-Version: 2
// 4. Media type en Accept header
GET /products
Accept: application/vnd.mycompany.v2+json
// 5. Versionado por fecha (estilo Stripe)
GET /products
Stripe-Version: 2024-04-10
// Ejemplo de respuesta v1 vs v2
// GET /v1/users/123
{
"id": 123,
"name": "Ana García",
"created": "2024-01-15" // String simple
}
// GET /v2/users/123
{
"id": 123,
"fullName": "Ana García", // Renombrado
"firstName": "Ana", // Campo nuevo
"lastName": "García", // Campo nuevo
"createdAt": "2024-01-15T10:30:00Z" // ISO 8601 completo
}