Boîte à outils API : Debugger plus vite, livrer plus tôt
Débogage JWT, codes de statut HTTP, formatage JSON, encodage Base64 et URL — les outils navigateur essentiels pour les développeurs API.
Il est 15h et l'API renvoie un 401. Le token a l'air valide. L'endpoint est correct. Les headers de requête semblent bons.
On colle le JWT dans un décodeur et le problème saute aux yeux : le claim exp a expiré il y a 12 minutes. La logique de rafraîchissement du token a un bug.
Ces cinq secondes de décodage viennent d'économiser une heure à fixer du code.
Le débogage JWT, c'est quotidien
Si on travaille avec une API moderne, on manipule des JWT en permanence. Tokens de connexion, auth service-à-service, flux OAuth — ils sont partout.
Le problème, c'est qu'un JWT ressemble à du charabia :
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Quels claims contient-il ? Quand expire-t-il ? Quel algorithme a été utilisé pour le signer ? Impossible à dire en le regardant.
Coller le token, voir instantanément le header, le payload et l'expiration. Pas de bibliothèque à installer. Pas de code à écrire. Juste des réponses.
Codes de statut HTTP : au-delà du 200 et du 404
Vite — quelle est la différence entre 401 et 403 ? Et 502 vs 503 ? Quand faut-il renvoyer un 409 plutôt qu'un 422 ?
La plupart des développeurs connaissent les plus courants, mais les API renvoient des dizaines de codes différents. Quand on reçoit un 429 inattendu ou un 307 déroutant, il faut savoir exactement ce que ça signifie.
Une référence des codes de statut HTTP dit ce que chaque code signifie, quand l'utiliser et les causes courantes. Plus rapide que Google, et pas besoin de fouiller les débats Stack Overflow.
Le formatage JSON n'est pas optionnel
Les API envoient du JSON. Les API reçoivent du JSON. Et la plupart du temps, ce JSON arrive en une seule ligne compressée sans espaces.
{"users":[{"id":1,"name":"Alice","roles":["admin","editor"],"settings":{"theme":"dark","notifications":{"email":true,"push":false}}}]}
Essayez de trouver une virgule manquante là-dedans. Ou de vérifier si un champ imbriqué existe. Ou de comparer deux réponses.
Coller le JSON compressé, obtenir un formatage avec une indentation correcte. Maintenant on peut vraiment le lire, repérer les erreurs et comparer les structures.
Base64 : le secret des headers d'auth
L'authentification API implique souvent de l'encodage Base64. Les headers Basic Auth sont username:password encodés en Base64. Les données binaires dans les payloads JSON sont encodées en Base64. Contenu de certificats, signatures de webhooks, valeurs chiffrées — tout en Base64.
Quand quelque chose ne marche pas, il faut décoder ce qui est réellement envoyé. Ou encoder une nouvelle valeur pour tester.
Un encodeur/décodeur Base64 gère les deux sens instantanément. Coller la chaîne encodée, voir la valeur originale. Taper une nouvelle valeur, obtenir la version encodée.
Scénario de debug courant : le header Basic Auth échoue. On le décode et on découvre un caractère de retour à la ligne en fin de mot de passe. Ça aurait pris bien plus longtemps à repérer dans le code.
L'encodage URL devient piégeux
Les paramètres de requête avec des caractères spéciaux nécessitent un encodage URL. Les espaces deviennent %20 (ou +). Les esperluettes deviennent %26. Les barres obliques deviennent %2F.
C'est important quand :
- On construit des endpoints de recherche avec des entrées utilisateur
- Les paramètres contiennent eux-mêmes des URL (callback URLs, redirect URIs)
- On débogue pourquoi un paramètre n'est pas correctement parsé
- Les clés API contiennent des caractères spéciaux
Un encodeur/décodeur URL montre exactement à quoi ressemble la version encodée/décodée. Particulièrement utile pour déboguer les callback URLs OAuth, qui sont souvent des URLs-dans-des-URLs et deviennent illisibles quand elles sont doublement encodées.
Workflow de debug réel
Comment ces outils s'intègrent dans une vraie session de debug API :
- La requête échoue — vérifier la signification du code de statut HTTP
- Problème d'auth ? — décoder le JWT pour vérifier les claims et l'expiration
- Problème de payload ? — formater le JSON pour inspecter la structure
- Problème de header ? — décoder le header d'auth Base64
- Parsing d'URL ? — décoder l'URL pour vérifier l'encodage des paramètres
Chaque étape prend quelques secondes. L'alternative — écrire des scripts jetables, installer des outils CLI, ou fouiller la documentation — prend des minutes à des heures.
Les garder toujours ouverts
Je garde ces outils dans des onglets épinglés. Pas parce que je ne sais pas faire de l'encodage Base64 en Python ou formater du JSON dans VS Code. Je sais. Mais le changement de contexte vers le terminal, écrire un petit script et le lancer, ça casse le flux de debug.
Ces outils sont de la vitesse de debug pure. Coller, voir le résultat, comprendre le problème, corriger le code. Le cycle de debug le plus rapide possible.
Le développement API, c'est 50% écrire du code et 50% comprendre pourquoi le code qu'on a écrit ne marche pas comme prévu. Les bons outils navigateur ne remplacent pas l'IDE ou le debugger — ils les complètent en rendant la partie "comprendre" plus rapide.