Como codificar e decodificar URLs

Se voce ja viu %20 em uma URL onde deveria estar um espaco, ou %C3%A9 onde pertence um caractere acentuado, voce encontrou a codificacao de URL. E uma parte fundamental de como a web funciona, e entende-la ajuda voce a depurar links quebrados, problemas de API e envios de formularios. Um codificador baseado em navegador lida com todo o trabalho localmente sem enviar seus dados para um servidor.

O que a codificacao de URL faz

URLs so podem conter um conjunto limitado de caracteres com seguranca: letras (A-Z, a-z), digitos (0-9) e alguns caracteres especiais (-, _, ., ~). Todo o resto (espacos, caracteres acentuados, emoji e simbolos como &, =, #, ?) deve ser convertido para um formato seguro.

A codificacao de URL (tambem chamada de codificacao percentual) substitui caracteres inseguros por um % seguido de seus valores de byte hexadecimais:

Quando voce precisa de codificacao de URL

• Parametros de consulta com caracteres especiais: uma consulta de pesquisa como preco > 100 & categoria = sapatos precisa de codificacao para funcionar em uma URL
• Caracteres nao ingleses em URLs: nomes, cidades ou conteudo em outros idiomas devem ser codificados
• Solicitacoes de API: ao construir chamadas de API manualmente, os valores dos parametros frequentemente precisam de codificacao
• Depuracao: quando uma URL nao esta funcionando, decodifica-la revela quais sao os valores reais
• Links de e-mail (mailto:): linhas de assunto e texto do corpo em links mailto precisam de codificacao
• URIs de redirecionamento OAuth: o parametro redirect_uri passado para provedores OAuth deve ser totalmente codificado
• Cargas uteis de webhook: strings de consulta em URLs de webhook entregues por servicos como Stripe ou Slack
• Links profundos para aplicativos moveis: esquemas de URL personalizados para aplicativos iOS/Android precisam de codificacao para manuseio seguro
• Consultas persistentes GraphQL: consultas com hash anexadas como parametros de URL precisam de codificacao
• Strings de conexao PostgreSQL: senhas e outros caracteres especiais em valores DATABASE_URL

Como codificar e decodificar

1. Escolha codificar ou decodificar: selecione a direcao. Escolha encodeURIComponent para parametros de consulta ou encodeURI para URLs completas.
2. Cole sua entrada: insira o texto ou URL. O resultado atualiza instantaneamente.
3. Copie a saida: use o resultado em seu codigo, solicitacao de API ou navegador.

Uma breve historia da codificacao de URL

A codificacao de URL foi definida pelo RFC 1738 em dezembro de 1994, junto com a especificacao URL original. O RFC foi escrito por Tim Berners-Lee (inventor da web) com contribuicao do Grupo de Trabalho URI do IETF. O esquema de codificacao original usava valores de byte ASCII: cada caractere reservado ou inseguro era codificado como % seguido de dois digitos hexadecimais.

A codificacao foi atualizada varias vezes:

• RFC 1738 (1994): especificacao URL original, somente ASCII
• RFC 2396 (1998): sintaxe mais rigorosa, separou caracteres «reservados» de «nao reservados»
• RFC 3986 (2005): especificacao URI atual, define dois modos de codificacao (caminho vs consulta), sequencias de bytes UTF-8 para nao-ASCII
• Padrao URL WHATWG (em andamento): a especificacao vivente padrao do navegador, usada por todos os navegadores modernos, regras ligeiramente diferentes do RFC 3986 para compatibilidade retroativa

A maior mudanca foi a mudanca para UTF-8 no RFC 3986. Antes disso, URLs codificadas eram somente ASCII, e caracteres nao latinos exigiam solucoes alternativas (Punycode para dominios, IDN para enderecos internacionais). Hoje, um «é» acentuado em uma URL codifica para %C3%A9 (seus dois bytes UTF-8), nao o byte Latin-1 %E9 que sistemas mais antigos produziriam.

encodeURI vs encodeURIComponent vs encodeURIFull

JavaScript tem tres funcoes de codificacao com comportamento sutilmente diferente:

Em Python:

• urllib.parse.quote() e como encodeURI (preserva /, mas nao :)
• urllib.parse.quote_plus() e como encodeURIComponent mas usa + para espacos
• urllib.parse.urlencode(dict) codifica strings de consulta inteiras

Em outras linguagens:

Armadilhas comuns

• Codificar toda a URL: se voce codificar https://example.com/search?q=hello, obtem https%3A%2F%2Fexample.com%2Fsearch%3Fq%3Dhello que nao e mais uma URL funcional. So codifique os valores, nao os caracteres estruturais.
• Codificacao dupla: codificar uma string ja codificada produz coisas como %2520 (o % fica codificado como %25). Se sua URL parecer errada, verifique se algo esta sendo codificado duas vezes.
• Espacos como + vs %20: em application/x-www-form-urlencoded (corpos POST de formulario), os espacos se tornam +. Em URLs, os espacos se tornam %20. A maioria dos servidores aceita ambos, mas alguns analisadores estritos nao.
• Codificar caracteres reservados incorretamente: ?, #, &, = tem significado especial na sintaxe URL. Se aparecerem em um valor, devem ser codificados; se aparecerem como sintaxe, nao devem ser.
• Esquecer de decodificar ao receber: se voce codifica um valor, envia, depois seu servidor le ?q=hello%20world literalmente sem decodificar, sua aplicacao ve hello%20world nao hello world. A maioria dos frameworks decodifica automaticamente, mas verifique em codigo personalizado.
• Confusao do sinal de mais: + e um mais literal em segmentos de caminho e um espaco em strings de consulta. Codifique sinais de mais reais como %2B em valores de consulta para evitar ambiguidade.
• UTF-8 vs outras codificacoes: se sua URL contem «résumé» e o servidor espera Latin-1 em vez de UTF-8, voce pode obter mojibake. A web moderna e UTF-8; sistemas legados nao sao.
• Limites de comprimento de URL: mesmo que nao haja limite estrito na especificacao, navegadores e servidores frequentemente limitam URLs a 2048-8192 caracteres. Dados pesadamente codificados podem atingir limites mais rapido do que o esperado.
• Cookies e cabecalhos Referer: URLs sao passadas em cabecalhos Referer e podem ser registradas. Dados sensiveis em URLs (senhas, tokens) vazam para logs e analise. Use corpos POST para dados sensiveis.
• Nomes de dominio nao-ASCII: dominios usam Punycode (RFC 3492), nao codificacao percentual. «münchen.de» se torna «xn--mnchen-3ya.de» em pesquisas DNS, nao «m%C3%BCnchen.de».

Exemplos trabalhados

Dicas

• Codifique valores, nao URLs inteiras: se voce codificar uma URL inteira, as barras e dois-pontos que estruturam a URL tambem serao codificados, quebrando-a. So codifique os valores dentro dos parametros de consulta.
• Codificacao dupla: codificar uma string ja codificada produz coisas como %2520 (o % fica codificado como %25). Se sua URL parecer errada, verifique se algo esta sendo codificado duas vezes.
• Decodifique para depuracao: quando uma solicitacao de API falha ou uma URL parece confusa, decodifique-a para ver os valores reais dos parametros. Isso frequentemente revela o problema imediatamente.
• Use as funcoes internas da sua linguagem: em codigo de producao, sempre use encodeURIComponent() (JavaScript), urllib.parse.quote() (Python) ou URLEncoder.encode() (Java) em vez de codificar manualmente.
• Teste com casos limite: tente entradas com espacos, acentos, emoji e caracteres especiais. Se sua codificacao funciona para todos eles, funciona.
• Verifique na barra de endereco do navegador: cole sua URL codificada em um navegador. Se a pagina carregar, a URL esta bem formada. Se nao, sua codificacao tem um bug.
• Use uma biblioteca de string de consulta para casos complexos: construir uma string de consulta a partir de um dicionario ou objeto (?a=1&b=2&c=3) e mais facil e mais seguro com uma funcao de biblioteca (urlencode em Python, URLSearchParams em JavaScript) do que com montagem manual.
• Conheca a diferenca entre codificacao de caminho e consulta: uma barra / em um segmento de caminho e estrutural; em um valor de consulta, deve ser codificada. RFC 3986 tem regras diferentes para cada.

Privacidade e URLs confidenciais

O codificador e decodificador de URL rodam inteiramente no seu navegador. As URLs que voce cola, o processamento intermediario e a saida codificada/decodificada ficam todos no seu dispositivo. Nada e enviado para um servidor, registrado ou compartilhado com ninguem.

Isso importa porque URLs frequentemente contem dados extremamente sensiveis: chaves e tokens de API em parametros de consulta, codigos de autorizacao OAuth que concedem acesso a conta, IDs de sessao, URLs assinadas para buckets S3 privados com credenciais incorporadas, tokens de login de link magico, URLs de redefinicao de senha, URLs internas de administracao que revelam a estrutura do produto, enderecos de e-mail de clientes em links de cancelamento de inscricao, dados pessoais em envios de formularios. Codificadores URL em nuvem registram cada colagem, as vezes os retem para «melhoria do servico», e estiveram envolvidos em vazamentos reais onde tokens de autenticacao colados foram extraidos por atacantes monitorando os logs. Um codificador baseado em navegador tem exposicao zero: a URL nunca sai da sua maquina.

A codificacao baseada em navegador tambem funciona offline depois que a pagina e carregada, util para codificar URLs em avioes, em ambientes seguros sem acesso a internet, ou em qualquer lugar onde voce nao pode ou nao deveria colar URLs portadoras de autenticacao em um servico de terceiros.