Codage d'URL Qu'est-ce qui est échappé et pourquoi votre API se casse sans cela

Votre appel à l'API semblait correct. L'endpoint correspondait, les en-têtes étaient bons, et la réponse retournait 400 Bad Request. Après vingt minutes de regard incessant, vous repérez le problème : une adresse e-mail dans la chaîne de requête contenant un signe qui a été décodé par le serveur comme un espace. C'est l'encodage par pourcentages en action, et cela casse les choses de manière difficile à déboguer. + Cet guide explique ce que fait réellement l'encodage par pourcentages, quels caractères doivent être encodés dans quels contextes, la difficulté rencontrée par tout le monde avec JavaScript, et comment utiliser un outil comme le

pour vérifier votre travail. Encodeur/Décodeur d'URL Ce que fait réellement l'encodage par pourcentages

Une URL ne peut contenir qu'un sous-ensemble de caractères ASCII. Tout ce qui est à l'exception de cela — les espaces, les caractères internationaux, les symboles ayant un sens particulier dans les URLs — doit être converti en un format sécurisé avant transmission.

L'encodage par pourcentages le fait en remplaçant chaque byte non sécurisé par un signe % suivi de deux chiffres hexadécimaux. Un espace devient

, un hash devient %20, un slash devient %23. Le nom vient de ce signe % initial. %2FLa spécification (RFC 3986) définit des « caractères non réservés » qui n'ont jamais besoin d'être encodés : les lettres (A–Z, a–z), les chiffres (0–9) et quatre symboles :

. Tout le reste est soit un caractère réservé (utilisé pour délimiter la structure de l'URL) soit un caractère qui doit être encodé. - _ . ~Les caractères qui cassent les APIs

Voici ceux qui causent le plus de dommages dans la pratique :

Contextes nécessitant l'encodage

La partie de l'URL que vous encoderez change ce qui doit être échappé.

URL complète

— Quand vous avez une URL complète à transmettre, vous souhaitez préserver sa structure. Les barres obliques, les points d'interrogation et les signes # restent tels qu'ils sont. Seuls les caractères en dehors de l'ensemble autorisé sont encodés. Valeur de chaîne de requête

— C'est là que vivent la plupart des bugs d'API. Chaque valeur dans une chaîne de requête doit être encodée afin que les caractères utilisés pour structurer la requête ( ) ne soient pas présents littéralement dans la valeur. Si le nom de l'utilisateur est « John & Jane », la chaîne de requête doit lire&, =, #, +, qui est interprétée par le serveur comme deux paramètres séparés. name=John%20%26%20Jane, et non pas name=John & Jane Segment de chemin

— Un segment de chemin est la partie entre les barres obliques. Si un segment contient une barre oblique (par exemple, un nom de fichier avec une barre oblique), il doit être encodé comme . Certains serveurs considèrent %2Fdans un chemin comme une préoccupation de sécurité ; connaissez votre backend avant de l'utiliser. %2F encodeURI vs encodeURIComponent — La difficulté avec JavaScript

JavaScript vous donne deux fonctions d'encodage intégrées, et l'utilisation de la mauvaise fonction est une erreur très fréquente.

Règle de base : utilisez

// encodeURI — encodes a full URL
// Preserves: : / ? # [ ] @ ! $ & ' ( ) * + , ; =
encodeURI("https://example.com/search?q=hello world&lang=en")
// → "https://example.com/search?q=hello%20world&lang=en"
// Note: & and = are NOT encoded — the query structure is preserved

// encodeURIComponent — encodes a single value
// Encodes everything except: A-Z a-z 0-9 - _ . ! ~ * ' ( )
encodeURIComponent("hello world&lang=en")
// → "hello%20world%26lang%3Den"
// Note: & and = ARE encoded — safe to use as a query value

// The bug: using encodeURI on a value
encodeURI("hello world&lang=en")
// → "hello%20world&lang=en"  ← & survives! Server sees two parameters.

// The correct approach for building query strings
const name = "John & Jane"
const email = "john+jane@example.com"
const url = `https://api.example.com/users?name=${encodeURIComponent(name)}&email=${encodeURIComponent(email)}`
// → "https://api.example.com/users?name=John%20%26%20Jane&email=john%2Bjane%40example.com"

sur les valeurs individuelles avant de les insérer dans une URL. Utilisez encodeURIComponent seulement lorsque vous avez une URL complète et que vous souhaitez la nettoyer sans détruire sa structure. encodeURI Le signe + : encodage de formulaire vs encodage par pourcentages

Quand un formulaire HTML soumet un champ avec

, les navigateurs utilisent method="GET"pour encoder les données. Dans ce format, les espaces deviennent application/x-www-form-urlencoded. Beaucoup de frameworks serveur (PHP, Django, Rails) décodent automatiquement + au lieu de %20comme un espace dans les chaînes de requête. + Cela crée un problème lorsque la valeur contient réellement un signe plus — par exemple, un numéro de téléphone comme

. Si vous le passez comme +44 7700 900000, le serveur décode le signe plus initial comme un espace et obtient +44.... La solution est d'encoder un signe plus littéral comme 44..., qui reste intact dans les deux schémas de décodage. %2BDans le cadre des API modernes, privilégiez

pour les espaces (ce que %20 produit) plutôt que de compter sur encodeURIComponent Double-encodage : quand l'encodage se fait mal +.

Le double-encodage survient quand vous encodé quelque chose qui est déjà encodé. Le signe % dans

est lui-même encodé en %20 — le serveur décode %2520 en un signe % littéral, donnant la chaîne %25 au lieu d'un espace. %20 Cela se manifeste généralement dans les cas suivants :

Vous stockez une URL dans une base de données et l'encodé à nouveau avant de l'utiliser

• Un framework ou une bibliothèque encodé des valeurs que vous avez déjà encodé manuellement
• Vous construisez une URL contenant une autre URL comme paramètre
• Pour éviter cela : encodé exactement une fois, au moment où vous composez l'URL. Si vous êtes incertain sur le fait qu'une valeur soit déjà encodée, décodez-la d'abord (avec

), puis re-encodé-la proprement. decodeURIComponentDéboguer l'encodage URL dans DevTools

Quand une requête API se comporte de manière inattendue, ouvrez DevTools (F12), allez dans l'onglet Network, et cliquez sur la requête échouée. Sous Headers, trouvez l'URL de la requête — le navigateur l'affiche sous sa forme brute après encodage. Sous Payload, vous pouvez voir les paramètres de requête décodés à leur valeur originale, ce qui facilite la détection de l'interprétation d'un ampersand comme un séparateur ou de son passage littéral.

Pour des tests manuels, un outil en ligne de décodage/encodage URL vous permet de coller une chaîne et de voir exactement quelle forme encodée elle prend — utile pour vérifier les valeurs avant de les intégrer dans une requête. L'

IO Tools URL Encoder/Decoder gère les deux directions et vous montre immédiatement le résultat. Encodage URL : quels caractères sont échappés et pourquoi votre API se casse sans cela 2

Vous aimerez peut-être aussi

Nouveau

Génération d'un palette de couleurs : Création d'une palette complète à partir d'un seul hexadécimal

En savoir plus "

Publié le 12 mai 2026

Nouveau

Vérification du schéma JSON : Capture des violations du contrat d'API avant leur livraison

En savoir plus "

Publié le 11 mai 2026

Nouveau

Vérification de la signature PDF : Ce que les développeurs doivent savoir

En savoir plus "

Publié le 10 mai 2026

Markdown vs HTML : Quand utiliser chacun pour les documents, les README et les API

En savoir plus "

Publié le 9 mai 2026