Encodeur et décodeur URL

Une URL n’admet qu’un jeu de caractères restreint, et plusieurs d’entre eux ont un rôle structurel : ? ouvre la query string, & sépare les paramètres, # introduit le fragment, / délimite les segments du chemin. L’encodage-pourcent (percent-encoding) remplace tous les autres caractères, ainsi que tout caractère réservé employé comme donnée, par un % suivi de deux chiffres hexadécimaux. Cet outil applique cette transformation à un seul composant, dans un sens comme dans l’autre.

Comment ça marche

Encoder passe votre texte à encodeURIComponent. Tout caractère situé hors de l’ensemble non réservé A–Z a–z 0–9 - _ . ! ~ * ' ( ) est converti en octets UTF-8, et chaque octet est écrit sous la forme %XX. Un espace devient %20, & devient %26, et é donne les deux octets %C3%A9. L’encodage n’échoue jamais.

Décoder passe par decodeURIComponent. L’opération échoue, avec un message explicite, lorsqu’un % n’est pas suivi de deux chiffres hexadécimaux ou lorsque les octets décodés ne forment pas de l’UTF-8 valide, par exemple un %E9 isolé, qui relève du Latin-1 et non de l’UTF-8. Un texte qui ne contient aucune séquence pourcent ressort inchangé du décodage.

Le mot clé, c’est composant. L’encodeur est fait pour une seule valeur, comme un paramètre de query string ou un segment de chemin, pas pour une URL entière. Passer https://example.com/a?b=c dans l’outil produit https%3A%2F%2Fexample.com%2Fa%3Fb%3Dc : c’est le bon résultat si vous voulez glisser cette URL comme valeur de paramètre (une cible de redirection, par exemple), et le mauvais si vous vouliez un lien utilisable.

Le signe plus

Les soumissions de formulaire encodées en application/x-www-form-urlencoded écrivent l’espace sous la forme +, et le + lui-même sous la forme %2B. Cette convention est propre aux formulaires HTML, pas aux URL en général. Cet outil suit les règles URI de la RFC 3986 : un espace donne toujours %20 et un + passe tel quel. Si un serveur se plaint que vos espaces lui arrivent sous forme de signes plus littéraux, c’est que l’émetteur a appliqué la règle des formulaires et le récepteur attendait la règle URI, ou l’inverse ; la solution consiste à expliciter la règle appliquée de chaque côté.

Encoder deux fois

Le bug le plus courant est le double encodage : une valeur qui contient déjà %20 est encodée une seconde fois et devient %2520. Cela arrive quand un framework encode automatiquement et que le développeur encode aussi à la main. Si, après un seul décodage, votre chaîne contient encore des séquences %XX, c’est qu’elle a été encodée deux fois ; décodez-la de nouveau et supprimez l’une des deux étapes d’encodage dans le code.

L’erreur inverse consiste à décoder trop tôt. Une valeur de paramètre contenant & doit rester encodée jusqu’à ce que la query string ait été découpée en paires, faute de quoi elle sera lue comme deux paramètres.

Équivalent en ligne de commande

jq sait encoder une valeur, et la bibliothèque standard de Python gère les deux sens :

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'

Attention : par défaut, quote de Python laisse / non encodé, contrairement à encodeURIComponent ; passez safe='' pour obtenir le même résultat.

Pour aller plus loin

Décider de ce qui va dans le chemin, de ce qui va dans la query string et de la forme que doivent prendre les identifiants contenant des caractères spéciaux relève de la conception d’API ; le guide Conception d’API REST couvre ces conventions. Le flux authorization code d’OAuth 2.0 repose presque entièrement sur des URL de redirection chargées de paramètres encodés, et le guide OAuth 2.0 montre concrètement à quoi ressemblent un redirect_uri et un state correctement encodés. Pour des octets qui doivent voyager sous forme de texte ailleurs que dans une URL, utilisez l’encodeur Base64.