Bonnes pratiques d'encodage d'URL pour les API REST

Pourquoi l'encodage d'URL est important pour les API

Un encodage d'URL correct est essentiel dans le développement d'API REST. Des URL mal encodées peuvent entraîner des requêtes défaillantes, des failles de sécurité, des pertes de données et des problèmes d'interopérabilité entre différents systèmes et langages de programmation. En tant que développeur d'API, vous devez comprendre à la fois comment encoder les URL lors de l'envoi des requêtes et comment les décoder lors de leur traitement.

Encoder les paramètres de chemin

Les API REST utilisent souvent des paramètres de chemin pour identifier les ressources. Lorsque ces paramètres contiennent des caractères spéciaux, un encodage correct est indispensable :

// Paramètre de chemin avec des caractères spéciaux
// Ressource : "Tom & Jerry's Show"
GET /api/shows/Tom%20%26%20Jerry%27s%20Show

// En JavaScript
const showName = "Tom & Jerry's Show";
const url = `/api/shows/${encodeURIComponent(showName)}`;

// Chemin contenant une barre oblique dans la valeur
// Fichier : "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

Encoder les paramètres de requête

Les paramètres de requête sont l'endroit le plus courant où surgissent les problèmes d'encodage. Encodez toujours à la fois les clés et les valeurs :

// Plusieurs paramètres avec des caractères spéciaux
GET /api/search?q=C%2B%2B%20programming&category=languages%20%26%20tools&page=1

// Avec URLSearchParams (recommandé)
const params = new URLSearchParams({
  q: 'C++ programming',
  category: 'languages & tools',
  page: '1'
});
const url = '/api/search?' + params.toString();

Gérer les tableaux et les objets dans les chaînes de requête

Les différents frameworks d'API gèrent les paramètres de type tableau de manière différente. Voici les conventions les plus courantes :

// Clés répétées (la plus courante)
GET /api/items?tag=javascript&tag=typescript&tag=react

// Notation avec crochets (PHP, Rails)
GET /api/items?tags[]=javascript&tags[]=typescript

// Séparés par des virgules (certaines API REST)
GET /api/items?tags=javascript,typescript,react

// Objets imbriqués (notation avec crochets)
GET /api/search?filter[status]=active&filter[sort]=date

Content-Type et encodage

L'en-tête Content-Type détermine la façon dont les données du corps de la requête sont encodées :

• application/x-www-form-urlencoded - Similaire aux chaînes de requête d'URL. Les clés et les valeurs sont encodées, les espaces deviennent +
• multipart/form-data - Utilisé pour l'envoi de fichiers. Chaque partie possède son propre encodage
• application/json - Format JSON. Aucun encodage d'URL n'est nécessaire pour le corps, mais le Content-Type doit être défini correctement

Considérations de sécurité pour les API

• Validez et assainissez toujours les paramètres d'URL décodés côté serveur
• Méfiez-vous des attaques par traversée de répertoire via des séquences encodées comme %2e%2e%2f (../)
• Mettez en place des limites de longueur d'URL pour prévenir les attaques par déni de service
• Ne faites jamais confiance à l'encodage côté client -- revalidez toujours côté serveur
• Surveillez les attaques par double encodage, où une entrée malveillante contourne les filtres après un premier passage de décodage
• Utilisez des requêtes paramétrées pour prévenir les injections SQL, même après décodage de l'URL

Tester l'encodage d'URL dans les API

Lorsque vous testez les points de terminaison de votre API, incluez des cas de test pour les scénarios suivants :

• Paramètres contenant des espaces (testez à la fois %20 et +)
• Paramètres contenant des caractères réservés (&, =, ?, #)
• Paramètres contenant des caractères Unicode
• Valeurs de paramètre vides
• Valeurs de paramètre très longues
• Entrées déjà encodées (détection du double encodage)
• Paramètres contenant des octets nuls (%00)