Detectar esquema de versionado de API desde la URL

Las API HTTP públicas anuncian su estilo de versionado en sitios distintos: un segmento de ruta como /v2/, una cadena de consulta como ? api_version=2, o en ningún lugar de la URL cuando se espera que los clientes envíen Accept u otras cabeceras personalizadas. Integraciones, pasarelas, generadores de SDK y rastreadores de documentación necesitan una respuesta determinista única sobre qué esquema usa un endpoint y qué token de versión lleva. Esta capacidad acepta una URL absoluta de API, rechaza cadenas que no sean URL http o https bien formadas y clasifica el esquema como path_based, query_param o header_implied. Si ni la ruta ni la consulta contienen un marcador convencional, el resultado es header_implied con has_version false, lo que indica que el versionado queda fuera de banda respecto a la URL.

Cómo se distinguen los esquemas por ruta, consulta y cabecera implícita

El versionado por ruta es la convención REST dominante: un segmento como v1, v2 o v1.2.3 aparece en el pathname, a menudo bajo /api/ o como primer segmento significativo tras el host. Este detector recorre los segmentos de izquierda a derecha y trata una coincidencia, sin distinguir mayúsculas, de v seguida de una versión numérica como path_based, devolviendo la parte numérica como version y el segmento original como version_raw con location apuntando a ese segmento (por ejemplo /v2). El versionado por parámetro de consulta coloca el token en la cadena de búsqueda bajo claves habituales: version, api_version, api-version, apiversion, ver y v. Cuando coincidirían ruta y consulta, path_based tiene prioridad porque la documentación REST pública casi siempre trata el segmento de ruta como contrato principal y la consulta como anulación secundaria. Si ninguna fuente aporta versión, el esquema es header_implied: la URL sola no codifica versión, lo que en API modernas suele significar Accept: application/vnd.example.v1+json, una cabecera X-API-Version personalizada o una superficie sin versionar.

Contrato de entrada, carga útil de éxito y errores de validación

Ejemplo: https://api.example.com/users? Envíe por POST un cuerpo JSON con un único campo de cadena obligatorio llamado url. El valor debe ser una URL absoluta bien formada con esquema http o https; rutas relativas, nombres de host sin esquema, cadenas vacías, tipos que no sean cadena y otros protocolos como ftp o mailto fallan con invalid_input y no se facturan. En caso de éxito la respuesta incluye siempre la url ecoada, scheme (path_based, query_param o header_implied), has_version (booleano), path (pathname) y host. Cuando has_version es true, la carga incluye también version (token normalizado), version_raw (como en la URL) y location (un puntero breve como /v2 o ? api_version=2). En resultados query_param, param_name registra la grafía original de la clave en la URL. Los campos opcionales se omiten en lugar de ponerse a null cuando has_version es false, manteniendo el contrato seguro para el DOM y fácil de renderizar. Ejemplo: https://api.example.com/v2/users produce scheme path_based, version 2 y location /v2. api_version=2 produce scheme query_param, version 2 y param_name api_version. Ejemplo: https://api.example.com/users sin marcadores de versión produce scheme header_implied y has_version false. Use la herramienta gratuita del navegador para una inspección puntual, o la API a $0.002 por elemento correcto cuando clasifique endpoints en lote desde un inventario o un rastreo OpenAPI.

Dónde aporta valor la detección del versionado en la URL

Los equipos de plataforma inventarian cientos de URL base internas y de socios y necesitan una etiqueta coherente antes de enrutar el tráfico por una pasarela que impone ventanas de deprecación. La validación fallida no consume saldo. Los generadores de SDK y las herramientas de andamiaje de clientes ramifican plantillas según si el servidor espera /vN/ en la ruta, un indicador de consulta o solo versionado por cabecera; un clasificador puro evita expresiones regulares frágiles repartidas por repositorios. Los sitios de documentación y los mercados de API muestran insignias del estilo de versionado junto a cada ficha; alimentarlos con este endpoint alinea la copia de marketing con la forma real de la URL. Las revisiones de seguridad y cumplimiento suelen preguntar si los hosts de producción aún exponen rutas sin versionar o esquemas mixtos que complican el despliegue de cambios incompatibles; exportar scheme y has_version a una hoja responde en un solo paso. Los trabajos de CI pueden rechazar una solicitud de fusión cuando una URL base de servicio nueva pasa en silencio de path_based a header_implied sin un ADR. Como la implementación es parse puro de nivel A, cada llamada correcta cuesta el precio base publicado $0.002, sin tokens de modelo ni descarga del host objetivo.