Codificador y decodificador URL

Una URL solo admite un conjunto limitado de caracteres, y varios de ellos tienen un significado estructural: ? abre la query string, & separa los parámetros, # inicia el fragmento y / divide los segmentos de la ruta. La codificación porcentual (percent-encoding) sustituye cualquier otro carácter, y cualquier carácter reservado que se use como dato, por un % seguido de dos dígitos hexadecimales. Esta herramienta aplica esa transformación a un único componente y también la deshace.

Cómo funciona

Codificar pasa tu texto por encodeURIComponent. Todo carácter que no pertenezca al conjunto no reservado A–Z a–z 0–9 - _ . ! ~ * ' ( ) se convierte a bytes UTF-8, y cada byte se escribe como %XX. Un espacio se convierte en %20, & en %26 y é en los dos bytes %C3%A9. La codificación nunca falla.

Decodificar usa decodeURIComponent. Falla, con un mensaje claro, cuando un % no va seguido de dos dígitos hexadecimales o cuando los bytes decodificados no forman UTF-8 válido; por ejemplo, un %E9 suelto, que es Latin-1 y no UTF-8. Un texto sin secuencias porcentuales queda igual al decodificarlo.

La palabra clave es componente. El codificador está pensado para un solo valor, como un parámetro de la query string o un segmento de ruta, no para una URL completa. Si le pasas https://example.com/a?b=c, obtienes https%3A%2F%2Fexample.com%2Fa%3Fb%3Dc, que es el resultado correcto para incrustar esa URL como valor de un parámetro (por ejemplo, un destino de redirección) y el incorrecto si lo que querías era un enlace utilizable.

El signo más

Los envíos de formularios codificados como application/x-www-form-urlencoded escriben el espacio como +, y el propio + como %2B. Esa convención es de los formularios HTML, no de las URL en general. Esta herramienta sigue las reglas de URI de la RFC 3986, así que un espacio siempre es %20 y un + pasa sin cambios. Si un servidor se queja de que tus espacios le llegan como signos más literales, el emisor aplicó la regla de los formularios y el receptor esperaba la de URI, o al revés; la solución es dejar explícito qué regla aplica cada lado.

Codificar dos veces

El bug más habitual es la doble codificación: un valor que ya contiene %20 se vuelve a codificar y se convierte en %2520. Pasa cuando un framework codifica automáticamente y el desarrollador también codifica a mano. Si después de decodificar una vez tu cadena todavía conserva secuencias %XX, es que se codificó dos veces; vuelve a decodificarla y elimina uno de los pasos de codificación del código.

El error contrario es decodificar demasiado pronto. Un valor de parámetro que contiene & debe seguir codificado hasta que la query string se haya dividido en pares; de lo contrario, se leerá como dos parámetros.

Equivalente en la línea de comandos

jq puede codificar un valor, y la biblioteca estándar de Python cubre ambos sentidos:

jq -rn --arg s 'a b&c=d' '$s | @uri'                     # a%20b%26c%3Dd
python3 -c 'import urllib.parse as u,sys; print(u.unquote(sys.argv[1]))' 'a%20b%26c'

Ten en cuenta que quote de Python deja / sin codificar por defecto, a diferencia de encodeURIComponent; pasa safe='' para obtener el mismo resultado.

Para saber más

Decidir qué va en la ruta, qué va en la query string y qué aspecto deben tener los identificadores con caracteres especiales forma parte del diseño de APIs; la guía de diseño de APIs REST cubre esas convenciones. El flujo authorization code de OAuth 2.0 se construye casi por completo con URL de redirección que llevan parámetros codificados, y la guía de OAuth 2.0 muestra en la práctica cómo se ven un redirect_uri y un state bien codificados. Para bytes que deben viajar como texto fuera de una URL, usa el codificador Base64.