Detectar esquema de versionamento de API pela URL

APIs HTTP públicas anunciam o estilo de versionamento em lugares diferentes: um segmento de caminho como /v2/, uma query string como ? api_version=2, ou em nenhum lugar da URL quando se espera que os clientes enviem Accept ou cabeçalhos personalizados. Integrações, gateways, geradores de SDK e rastreadores de documentação precisam de uma resposta determinística única sobre qual esquema um endpoint usa e qual token de versão carrega. Esta capacidade aceita uma URL absoluta de API, rejeita strings que não sejam URL http ou https bem formadas e classifica o esquema como path_based, query_param ou header_implied. Se nem o caminho nem a consulta contiverem um marcador convencional, o resultado é header_implied com has_version false, sinalizando que o versionamento fica fora de banda em relação à URL.

Como se distinguem os esquemas por caminho, consulta e cabeçalho implícito

O versionamento por caminho é a convenção REST dominante: um segmento como v1, v2 ou v1.2.3 aparece no pathname, muitas vezes sob /api/ ou como o primeiro segmento significativo após o host. Este detector percorre os segmentos da esquerda para a direita e trata uma correspondência, sem distinguir maiúsculas, de v seguida de versão numérica como path_based, devolvendo a parte numérica como version e o segmento original como version_raw com location apontando para esse segmento (por exemplo /v2). O versionamento por parâmetro de consulta coloca o token na string de busca sob chaves comuns: version, api_version, api-version, apiversion, ver e v. Quando caminho e consulta coincidiriam, path_based tem prioridade porque a documentação REST pública quase sempre trata o segmento de caminho como contrato principal e a consulta como sobreposição secundária. Se nenhuma fonte fornecer versão, o esquema é header_implied: a URL sozinha não codifica versão, o que em APIs modernas costuma significar Accept: application/vnd.example.v1+json, um cabeçalho X-API-Version personalizado ou uma superfície sem versionamento.

Contrato de entrada, carga de sucesso e erros de validação

Exemplo: https://api.example.com/users? Envie por POST um corpo JSON com um único campo string obrigatório chamado url. O valor deve ser uma URL absoluta bem formada com esquema http ou https; caminhos relativos, hostnames sem esquema, strings vazias, tipos que não sejam string e outros protocolos como ftp ou mailto falham com invalid_input e não são cobrados. Em caso de sucesso a resposta sempre inclui a url ecoada, scheme (path_based, query_param ou header_implied), has_version (booleano), path (pathname) e host. Quando has_version é true, a carga também inclui version (token normalizado), version_raw (como na URL) e location (um ponteiro curto como /v2 ou ? api_version=2). Em resultados query_param, param_name registra a grafia original da chave na URL. Campos opcionais são omitidos em vez de nulos quando has_version é false, mantendo o contrato seguro para o DOM e fácil de renderizar. Exemplo: https://api.example.com/v2/users produz scheme path_based, version 2 e location /v2. api_version=2 produz scheme query_param, version 2 e param_name api_version. Exemplo: https://api.example.com/users sem marcadores de versão produz scheme header_implied e has_version false. Use a ferramenta gratuita do navegador para uma inspeção pontual, ou a API a US$ 0,002 por item bem-sucedido ao classificar endpoints em lote a partir de um inventário ou de um rastreio OpenAPI.

Onde a detecção de versionamento na URL vale a pena

Equipes de plataforma inventariam centenas de URLs base internas e de parceiros e precisam de um rótulo consistente antes de rotear o tráfego por um gateway que impõe janelas de depreciação. Validação falha não consome saldo. Geradores de SDK e ferramentas de scaffolding de clientes ramificam templates conforme o servidor espera /vN/ no caminho, um flag de consulta ou só versionamento por cabeçalho; um classificador puro evita regexes frágeis espalhadas por repositórios. Sites de documentação e marketplaces de API mostram selos do estilo de versionamento ao lado de cada listagem; alimentá-los com este endpoint alinha o texto de marketing à forma real da URL. Revisões de segurança e conformidade costumam perguntar se hosts de produção ainda expõem caminhos sem versão ou esquemas mistos que complicam o rollout de mudanças incompatíveis; exportar scheme e has_version para uma planilha responde em um único passo. Jobs de CI podem reprovar um pull request quando a URL base de um serviço novo muda em silêncio de path_based para header_implied sem um ADR. Como a implementação é parse puro de tier A, cada chamada bem-sucedida custa o preço base publicado US$ 0,002, sem tokens de modelo e sem fetch do host alvo.