Config (JSON)

URL

O que é o Construtor de URL?

Você passa um objeto JSON descrevendo as partes de uma URL — protocolo, host, caminho, parâmetros de query, hash — e a ferramenta devolve a URL montada, devidamente codificada em porcentagem. Por baixo dos panos ele usa a URL API nativa do navegador, então a saída bate exatamente com o que um navegador emitiria se você construísse a URL em JavaScript.

O motivo de existir: montar URL na mão é onde os bugs se escondem. Você esquece de codificar um espaço no nome de um cliente, codifica em dobro uma barra que já estava codificada, mistura ? e &, perde um valor por usar + em vez de %20. A spec URL do WHATWG define exatamente uma resposta certa para cada entrada, e é isso que você recebe aqui. Chaves de query repetidas (ex.: tag=red&tag=blue) são suportadas passando um array — o mesmo formato que o URLSearchParams aceita.

Roda inteiro no seu navegador. A config JSON e a URL montada nunca saem da sua máquina. As regras de codificação vêm direto do RFC 3986 e dos refinamentos do WHATWG por cima. Combine com o URL Parser quando quiser fazer um ida-e-volta de uma URL através de um formulário estruturado.

Como usar o Construtor de URL

Três passos. Cada um corresponde a um botão nesta página.

Cole uma config JSON

Cole um objeto JSON à esquerda descrevendo as partes da URL. protocol e host são obrigatórios; o resto é opcional. Clique em Exemplo para carregar um caso realista com vários parâmetros e um hash:

{
  "protocol": "https",
  "host": "api.shop.example.com",
  "pathname": "/v1/orders",
  "searchParams": {
    "customer": "Ava Chen",
    "status": "active",
    "total[gte]": "49.99",
    "page": "2"
  },
  "hash": "summary"
}

Campos opcionais: port, username, password, hash. Dentro de searchParams, uma string é um valor; um array são chaves repetidas.

Leia a URL montada

O painel da direita mostra a URL montada. Espaços viram + na query string, colchetes viram %5B/%5D, o caminho é normalizado — a mesma codificação que o padrão URL define. Atualiza enquanto você digita.

Copie ou baixe

Clique em Copiar para mandar a URL para a área de transferência, ou Baixar para salvar como arquivo de texto. Use Limpar no painel de entrada para começar do zero.

Quando você usaria isso de verdade

Criar fixtures de teste para um cliente HTTP

Você está escrevendo um teste que bate em /v1/orders com oito parâmetros, dois com espaços e um repetido. Digitar a URL codificada à mão no teste dá ruim. Monte a partir de um objeto JSON que dá pra copiar de um log real, cole a URL resultante na asserção. Pronto.

Construir URLs de autorização OAuth

URLs de autorização OAuth empilham client_id, redirect_uri, scope, state, response_type e code_challenge na query string. A RFC 6749 exige esses nomes exatos e um redirect_uri que já esteja codificado uma vez antes da URL inteira ser codificada de novo. O construtor cuida disso de forma transparente — você dá os valores brutos e ele faz a coisa certa.

Gerar URLs de analytics ou de compartilhamento em script

Quando você está gerando uma URL de campanha com parâmetros UTM, os valores vêm com frequência de uma planilha onde utm_campaign contém espaços, ampersands e algum emoji ocasional. Deixar o construtor cuidar da codificação é mais seguro do que um template de string. A saída é idêntica à que o módulo URL do Node produziria.

Reproduzir um bug de um chamado de suporte

Um cliente reporta que uma busca com q=résumé writer dá 500 na API. Você quer reproduzir a requisição exata. Monte a URL a partir de JSON e curl nela. O acento no e e o espaço são codificados do jeito que o navegador teria mandado — sem chute.

Perguntas frequentes

Qual a diferença entre o Construtor de URL e concatenar strings na mão?

A codificação. https://api.example.com/orders?customer=Ava Chen não é uma URL válida — o espaço quebra. O construtor usa URLSearchParams internamente, que codifica esse espaço como + na query e %20 no caminho. Concatenação manual erra um dos dois cedo ou tarde.

Como mando um parâmetro duas vezes (ex.: ?tag=red&tag=blue)?

Use um array como valor: "tag": ["red", "blue"]. O construtor emite tag=red&tag=blue na ordem que você forneceu. Bate com a spec do URLSearchParams.

Preciso incluir os dois pontos depois do protocolo (https:) ou só https?

Tanto faz. O construtor normaliza tanto "protocol": "https" quanto "protocol": "https:" para https:. O mesmo vale para http, ftp, mailto e schemes customizados.

Posso incluir credenciais (usuário/senha) na URL?

Pode — defina "username" e "password" na config. Eles aparecem antes do host como user:pass@host. Só fique atento que a RFC 3986 §3.2.1 alerta contra isso em URLs de produção, porque param no histórico do navegador, em logs de servidor e em caches de proxy.

Por que meu espaço vira + em vez de %20?

Espaços no componente de query são tipicamente codificados como + conforme as regras de application/x-www-form-urlencoded — é o que o URLSearchParams emite. Espaços no caminho são codificados como %20. Ambos são válidos; servidores decodificam as duas formas. Se o seu servidor está quebrado e só lida com %20, você tem um problema maior do que esta ferramenta.

Que formato o JSON de entrada deve seguir?

JSON padrão — veja json.org ou ECMA-404 para a spec. Chaves são strings, valores são strings ou (no caso de searchParams) arrays de strings. Sem comentários. Vírgula no final não é permitida.

Outras ferramentas de URL & JSON

Construir é uma direção. Aqui vai o que combina naturalmente: