Definition
Cuando necesitas versionar tu API pero no quieres llenar tus rutas URL con prefijos /v1/ o /v2/, el versionado por parámetro de consulta ofrece una alternativa elegante. En lugar de cambiar el endpoint en sí, simplemente añades un parámetro de versión a tus peticiones: /products?version=2 o /users?api-version=2.1. La URL base permanece limpia, y los clientes declaran explícitamente qué versión quieren con cada petición.
Este enfoque se sitúa entre el versionado por ruta (como /v1/products) y el versionado por cabecera (usando cabeceras personalizadas). Es más visible que las cabeceras ya que puedes verlo directamente en la URL, pero más flexible que el versionado por ruta ya que no necesitas diferentes manejadores de rutas para cada versión. La versión viaja con la petición a la vista, facilitando la depuración - puedes mirar logs o las herramientas de desarrollador del navegador e inmediatamente ver qué versión se llamó.
El versionado por parámetro de consulta es particularmente popular con APIs que quieren hacer el versionado opcional. Muchas implementaciones usan por defecto la última versión estable cuando no se proporciona ningún parámetro, solo requiriendo especificación explícita de versión cuando los clientes necesitan compatibilidad hacia atrás. Esto hace que la API se sienta más simple para nuevas integraciones mientras da a usuarios avanzados el control que necesitan. La contrapartida es que las versiones pueden pasarse por alto u olvidarse fácilmente, y el caching se vuelve más complicado ya que la misma ruta puede devolver contenido diferente basándose en el parámetro.
Example
APIs de Azure Cloud: Microsoft Azure usa versionado por parámetro de consulta en la mayoría de sus servicios. Cuando llamas a Azure Storage, incluyes ?api-version=2023-11-03 con cada petición. Esto permite a Azure mantener docenas de versiones de API simultáneamente - crítico para clientes empresariales que no pueden actualizar sus integraciones de la noche a la mañana. Si olvidas el parámetro de versión, Azure devuelve un error diciéndote qué versiones están disponibles.
APIs de Google Cloud: Muchos servicios de Google Cloud usan un patrón similar. Cloud Storage acepta parámetros ?v=2 o ?v=3. Lo ingenioso es cómo manejan los defaults - algunos endpoints usan por defecto la última versión para nuevas características mientras otros requieren versionado explícito para operaciones críticas de estabilidad como manipulación de datos.
AWS API Gateway: Cuando construyes APIs en AWS API Gateway, el versionado por parámetro de consulta es una opción de primera clase. Puedes configurar variables de stage que mapean parámetros de versión a diferentes funciones Lambda o servicios backend. Una petición a /products?version=1 podría enrutar a tu servicio legacy en Node.js mientras ?version=2 enruta a tu nuevo servicio en Go.
Parámetros Especiales de Stripe: Aunque Stripe usa principalmente versionado por cabecera, usan parámetros de consulta para características específicas de opt-in. Parámetros como ?expand[]=customer o ?stripe_version=2023-10-16 dan a los clientes control detallado sobre formato de respuesta y comportamiento. Este enfoque híbrido da lo mejor de ambos mundos.
APIs Empresariales Internas: Muchas grandes empresas usan versionado por parámetro de consulta para APIs internas porque es fácil de implementar y depurar. Una llamada como /api/employees?v=3&department=engineering hace obvio en logs qué versión se llamó. Cuando algo falla en producción, los ingenieros pueden ver inmediatamente la versión sin buscar en cabeceras de petición.
Analogía
El Menú de Restaurante con Secciones: Imagina un restaurante donde el menú ha evolucionado con el tiempo. En lugar de reimprimir todo o tener libritos separados de “menú clásico” y “menú nuevo”, tienen un menú unificado donde puedes especificar tu preferencia. “Tomaré la pasta” usa por defecto la receta actual, pero puedes decir “Tomaré la pasta, receta original” para obtener la versión clásica. El nombre del plato permanece igual; tu preferencia se anota por separado.
El Selector de Calidad de Streaming: Cuando ves Netflix o YouTube, la URL del vídeo es la misma, pero puedes añadir preferencias de calidad. video.mp4?quality=720p vs video.mp4?quality=4k obtiene el mismo contenido en diferentes formatos. El versionado por parámetro de consulta funciona idénticamente - mismo endpoint, diferente comportamiento basado en el parámetro que proporcionas.
El Edificio con Múltiples Ascensores: Piensa en un edificio de oficinas donde todos los ascensores van a todas las plantas, pero algunos son express. Pulsas tu planta (el endpoint), luego seleccionas express o local (el parámetro de versión). El destino es el mismo; el parámetro cambia cómo llegas allí. Clientes antiguos usan el ascensor local (versión estable); clientes nuevos pueden elegir express (última versión).
Opciones de Instalación de Software: Cuando descargas software, a menudo eliges entre “Instalación Estándar” e “Instalación Personalizada”. La URL de descarga podría ser la misma, pero ?type=standard vs ?type=custom cambia lo que obtienes. Estás solicitando el mismo producto con diferentes configuraciones - exactamente cómo funciona el versionado por parámetro de consulta para APIs.
Code Example
// Query parameter versioning
GET https://api.company.com/products?version=1
GET https://api.company.com/products?version=2
GET https://api.company.com/products?api-version=2.1
// Can combine with other parameters
GET https://api.company.com/products?version=2&limit=50&category=electronics
// Default version when omitted
GET https://api.company.com/products // Uses latest stable (v2)
// Error response for unsupported version
GET https://api.company.com/products?version=99
[HTTP/1.1](https://reference.apios.info/es/terms/http-1-1/) 400 Bad Request
{
"error": "UnsupportedVersion",
"message": "Version 99 is not supported. Available: 1, 2",
"supportedVersions": [1, 2]
}