Dépannage réseau des REST API avec exemples pratiques : guide opérationnel

Introduction

Les requêtes REST API transitent par plusieurs couches : client, DNS, routage, pare‑feu/ACL, terminaison TLS, reverse proxy/équilibreur de charge et service applicatif. Quand « ça casse », les symptômes peuvent être trompeurs. Ce guide propose une méthode sûre, par couches, pour isoler et réparer les problèmes réseau d'une REST API avec des commandes de diagnostic en lecture seule, des attentes explicites, et des exemples construits. Nous utiliserons des hôtes fictifs comme api.example.test et 10.0.1.20.

Au fil de la démarche, nous garderons un vocabulaire familier des praticiens : REST API networking, REST API DNS, REST API ports, REST API connectivity et REST API network troubleshooting, tout en privilégiant des formulations naturelles en français.

Cartographie rapide symptômes ↔ couches

Inventaire des versions et de l'environnement

Avant tout changement, consignez les faits qui serviront de base de test. Cela réduit les variables et évite les fausses pistes.

• Inventaire des endpoints
• URL(s) de base de l'API : ex. https://api.example.test
• Route(s) de santé : ex. /health ou /status
• Protocole attendu : HTTP ou HTTPS
• Ports attendus : 80/443 en externe ; ports internes (ex. 3000 pour Express) si pertinents
• Proxys inverses ou load balancers sur le chemin : ex. nginx sur lb.example.test
• Schéma de topologie (texte suffisant)
• Client -> DNS -> Internet/Réseau d'entreprise -> LB/Proxy -> Hôte API -> Dépendances (ex. MongoDB)
• Versions
• OS : ex. Ubuntu 22.04, Windows 11, macOS 14
• Runtime : ex. Node.js 18.x pour une API Express (exemple construit)
• TLS : où se fait la terminaison (proxy vs app)
• Données DNS
• Zone faisant autorité : qui gère api.example.test
• Types d'enregistrements : A/AAAA/CNAME
• IPs résolues et TTLs actuels
• Contrôles d'accès
• Règles de sécurité/pare‑feu ouvrant les ports et plages sources nécessaires
• Fenêtre de changement connue
• Modifs récentes de DNS, certificats, routage ou déploiements

Prérequis pour suivre ce guide :

• Accès shell à un client joignable vers le chemin réseau de l'API.
• Outils de base installés :
• Linux/macOS : dig (ou nslookup), curl, nc (netcat), traceroute, openssl, ss (ou netstat)
• Windows : nslookup, curl.exe, tracert, Test-NetConnection (PowerShell), netstat ; openssl si présent
• Accès en lecture aux journaux du serveur API si possible.

Chemin de configuration sûr

Procédez du moins intrusif au plus intrusif, et du local vers le distant. Gardez chaque changement limité et réversible.

1. Prouver que le service fonctionne en local (exemple construit)

• Sur l'hôte API, confirmez que le service écoute l'adresse et le port attendus.

# Linux
ss -lntp | grep ":3000"

# macOS (peut utiliser lsof)
lsof -nP -iTCP:3000 -sTCP:LISTEN

# Windows
netstat -ano | findstr LISTENING | findstr :3000

Attendu : un listener sur 127.0.0.1:3000 ou 0.0.0.0:3000 (ou votre port). Si rien n'écoute, corrigez le service avant de tester le réseau.

• Tapez une route de santé locale depuis l'hôte API.

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/health

Attendu : 200. Sinon, vérifiez les journaux et la configuration applicative.

1. Valider le DNS sans changer les enregistrements globaux

• Résolvez le nom pour confirmer la cible actuelle.

# Linux/macOS
dig +short api.example.test

# Windows
nslookup api.example.test

Attendu : les IP visées. Si non, n'altérez pas le DNS système. Faites plutôt un test ciblé.

• Surcharge ciblée d'hôte pour curl avec --resolve (ne modifie pas le système).

# Tester HTTPS vers une IP spécifique en conservant SNI/Host
curl -v --resolve api.example.test:443:203.0.113.10 https://api.example.test/health

Attendu : 200 si le service sur 203.0.113.10 est correct et si le certificat TLS correspond à api.example.test.

1. Prouver la joignabilité TCP avant la logique HTTP

# Linux/macOS
nc -vz api.example.test 443

# Windows PowerShell
Test-NetConnection -ComputerName api.example.test -Port 443

Attendu : message de succès. Si time‑out, suspectez routage/pare‑feu. Si « refused », suspectez l'absence d'écouteur ou un port fermé côté destination.

1. Valider TLS tôt si vous utilisez HTTPS

openssl s_client -connect api.example.test:443 -servername api.example.test -tls1_2 -brief < /dev/null

Attendu : session établie, chaîne valide, SNI correspondant à api.example.test, protocole/chiffrement acceptables. Corrigez TLS avant de déboguer les routes HTTP si la vérification échoue.

1. Tester ensuite les flux HTTP complets

curl -v https://api.example.test/health

Attendu : 200 et en‑têtes corrects. Comparez un appel direct à l'IP d'origine (via --resolve) et un appel via le load balancer pour isoler un problème de proxy.

Vérification et diagnostics

Exécutez ces tests pour isoler chaque couche avec résultats attendus et exemples. Remplacez hôtes, ports et IPs par les vôtres.

Exactitude DNS

# Enregistrements A/AAAA
dig +nocmd api.example.test A +noall +answer

dig +nocmd api.example.test AAAA +noall +answer

# Tracer le chemin de résolution
dig +trace api.example.test

# Windows
nslookup api.example.test

Attendu : A/AAAA pointent vers les bonnes IP, et la trace montre les serveurs faisant autorité sans SERVFAIL. Si le DNS est faux, corrigez à la source et respectez les TTL.

Connectivité TCP

# Tester uniquement la poignée de main TCP
nc -vz api.example.test 443

# Windows
Test-NetConnection -ComputerName api.example.test -Port 443 | Select-Object -Property ComputerName, RemotePort, TcpTestSucceeded

Attendu : TcpTestSucceeded: True (Windows) ou « succeeded » (nc). Si bloqué, capturez l'étape de défaillance avec traceroute.

Chemin de routage

# Linux/macOS
traceroute -n api.example.test

# Windows
tracert -d api.example.test

Attendu : un chemin complet vers l'IP de destination. Des time‑outs ou boucles indiquent un problème de routage ou d'ACL.

Écoutes locales et distantes

# Sur l'hôte API
ss -lntp | grep ":443\|:3000"

# Alternativement
netstat -tulpen 2>/dev/null | grep ":443\|:3000"

# Windows (hôte API)
netstat -ano | findstr LISTENING | findstr ":443 :3000"

Attendu : le service (ex. node, nginx) lié à l'adresse et au port attendus. Un bind sur 127.0.0.1 pour un service externe explique souvent un « connection refused » à distance.

Inspection TLS

openssl s_client -connect api.example.test:443 -servername api.example.test -showcerts < /dev/null | sed -n '1,15p'

Vérifiez :

• Le sujet et les SAN du certificat incluent api.example.test.
• Certificat non expiré ; chaîne complète.
• Protocole négocié acceptable (TLSv1.2 ou plus récent).

Si SNI est requis et omis, le serveur peut présenter le mauvais certificat.

Attendus HTTP

# Vérification du statut uniquement
curl -s -o /dev/null -w "%{http_code}\n" https://api.example.test/health

# En-têtes verbeux
curl -I -v https://api.example.test/health

Attendu :

• 200 OK pour /health.
• En‑têtes Server et Date présents.
• Si derrière un proxy, possiblement Via et X‑Forwarded-*.

Comparez via le load balancer et l'origine (avec --resolve) pour isoler les différences.

CORS (symptôme côté navigateur)

Les erreurs CORS relèvent de la couche applicative, pas de la joignabilité réseau, mais on les signale souvent comme « l'API ne marche pas » côté frontend. Vérifiez les en‑têtes via curl :

curl -s -D - https://api.example.test/route -o /dev/null | grep -i "access-control-allow-"

Attendu : Access-Control-Allow-Origin avec l'origine correcte ou *. Ajustez uniquement à la couche API ou proxy qui émet ces en‑têtes ; n'altérez ni DNS ni pare‑feu pour un problème CORS.

Scénario minimal de bout en bout (exemple construit)

• API Express interne sur 10.0.1.20:3000 derrière nginx terminant TLS sur 443 à 203.0.113.10.
• Test de l'origine directe : curl -v --resolve api.example.test:443:203.0.113.10 https://api.example.test/health
• Test via DNS : curl -v https://api.example.test/health

Si l'accès direct réussit mais pas le chemin DNS, le problème se situe jusqu'au LB inclus (DNS, route, pare‑feu, configuration proxy). Si les deux échouent, suspectez le service d'origine ou le pare‑feu de l'hôte.

Diagnostics par tâche et OS

Modes de panne et remédiation

1. Cible DNS erronée ou TTL obsolète

• Symptôme : curl vers le nom atteint le mauvais serveur ; --resolve vers l'IP voulue fonctionne.
• Preuve : dig +short renvoie des IP inattendues ; TTL élevé.
• Correctif : mettez à jour A/AAAA/CNAME à la zone faisant autorité. Pour une bascule progressive, abaissez le TTL au moins une période avant, puis mettez à jour.
• Retour arrière : rétablissez les anciennes valeurs. Gardez un export préalable de la zone. Vérifiez avec dig +trace et purge des caches clients.
• Vérifier : dig +short et curl -v suivent la bonne cible ; latence et en‑têtes correspondent au backend voulu.

1. Port fermé ou filtré par pare‑feu/ACL

• Symptôme : nc/Test-NetConnection en time‑out ; traceroute atteint le réseau mais l'init TCP échoue.
• Preuve : règles de pare‑feu hôte bloquant l'entrée 443 ; ACL réseau bloquant vos CIDR source.
• Correctif (hôte) : autorisez l'entrée vers le port du service depuis les sources requises uniquement.
• Linux (ex. ufw ; adaptez à votre pare‑feu) :

ufw allow proto tcp from 198.51.100.0/24 to any port 443 comment 'allow API clients'
ufw status numbered

• Windows (PowerShell, admin) :

New-NetFirewallRule -DisplayName "Allow API 443" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow -RemoteAddress 198.51.100.0/24
Get-NetFirewallRule -DisplayName "Allow API 443" | Get-NetFirewallPortFilter

• Retour arrière : supprimez la règle et restaurez l'état antérieur.
• Linux (ufw) :

ufw status numbered
ufw delete <rule-number>

• Windows :

Remove-NetFirewallRule -DisplayName "Allow API 443"

• Vérifier : Test-NetConnection/nc réussit ; curl renvoie le statut HTTP attendu.

1. Service à l'écoute uniquement sur loopback

• Symptôme : curl 127.0.0.1:3000 en local renvoie 200, mais les clients distants ont « connection refused ».
• Preuve : ss/netstat montre 127.0.0.1:3000 et non 0.0.0.0:3000.
• Correctif : changez l'adresse de bind vers 0.0.0.0 ou l'IP d'interface ; redémarrez le service.
• Risque : exposer un port interne en externe. Associez un reverse proxy, des règles de pare‑feu, et positionnez la terminaison TLS en conséquence.
• Retour arrière : restaurez la conf précédente puis redémarrez.
• Vérifier : ss/netstat affiche le bon bind ; nc/curl distants réussissent.

1. Décalage TLS ou certificat expiré

• Symptôme : curl -v indique un échec de vérification de certificat ; avertissements navigateurs.
• Preuve : openssl s_client révèle un CN/SAN incorrects ou un certificat expiré.
• Correctif : installez un certificat dont les SAN incluent le hostname ; assurez l'usage de SNI si plusieurs certs sont servis.
• Test local temporaire : curl --insecure pour un test ponctuel en dev ; ne jamais en faire un correctif permanent.
• Retour arrière : réinstallez le certificat précédent fonctionnel, puis retentez le renouvellement/émission.
• Vérifier : openssl s_client montre une chaîne valide ; curl sans --insecure réussit.

1. Mauvais routage du load balancer/reverse proxy

• Symptôme : le chemin direct (via --resolve) fonctionne ; le chemin via LB échoue en 502/503.
• Preuve : curl -v montre des en‑têtes Via et 5xx ; logs du LB/proxy avec erreurs de connexion upstream.
• Correctif : corrigez l'adresse/port d'upstream, la santé applicative et le mode (pass‑through vs terminaison TLS).
• Retour arrière : revenez à la dernière configuration valide du LB.
• Vérifier : health checks au vert ; curl via LB renvoie 200.

1. Asymétrie de routes ou problèmes de NAT

• Symptôme : le SYN atteint le serveur mais les réponses ne reviennent pas ; time‑outs intermittents entre sous‑réseaux.
• Preuve : capture sur le serveur montrant SYN reçu, SYN‑ACK envoyé, mais rien côté client ; mauvaise passerelle dans la table de routage.
• Correctif : corrigez la passerelle par défaut ou les routes spécifiques. Assurez que NAT et groupes de sécurité autorisent le trafic retour.
• Retour arrière : restaurez la table de routage précédente.
• Vérifier : traceroute stable ; nc/Test-NetConnection réussissent de façon fiable.

1. Problèmes d'MTU/fragmentation (avancé)

• Symptôme : petites requêtes OK ; grandes poignées de main TLS ou réponses bloquent.
• Preuve : échec de la découverte PMTU ; tcpdump montre des retransmissions.
• Correctif : réduisez l'MTU sur l'interface affectée ou corrigez le segment réseau (ICMP PMTU autorisé). Testez en fenêtre de maintenance.
• Retour arrière : restaurez l'MTU précédent.
• Vérifier : grandes réponses et handshakes TLS aboutissent.

Checklist d'exploitation

1. Enregistrer les faits

• Nom d'hôte, IP(s) attendues, port(s), protocole.
• Changements récents et TTLs.

1. DNS

• dig/nslookup sur le nom ; confirmer A/AAAA.
• Si faux, tester la bonne cible avec curl --resolve.

1. Connectivité

• nc -vz ou Test-NetConnection vers le port. Si bloqué, inspecter pare‑feu/ACL.

1. Routage

• traceroute/tracert ; vérifier un chemin propre sans boucles/time‑outs.

1. Écouteurs

• ss/netstat sur l'hôte API ; confirmer bind et port corrects.

1. TLS

• openssl s_client ; valider CN/SAN, expiration et SNI.

1. Comportement HTTP

• curl -v sur la route de santé ; comparer via LB vs origine.
• Pour les signalements navigateur, valider les en‑têtes CORS via curl -I.

1. Corriger en sécurité

• Appliquer le plus petit changement expliquant le symptôme.
• Conserver des sauvegardes DNS/LB/pare‑feu.

1. Vérifier

• Rejouer l'appel en échec et les tests par couche.

1. Revenir en arrière si nécessaire

• Restaurer l'état connu fonctionnel ; revérifier la stabilité.

Conclusion

Un dépannage fiable d'une REST API repose sur une approche par couches : commencer localement, vérifier DNS et TCP avant la logique HTTP, puis élargir du service vers le proxy et le réseau. Pour chaque étape, définir le résultat attendu, savoir comment le vérifier et préparer un retour arrière. Avec cette méthode, ses commandes sûres et sa checklist, les développeurs, équipes DevOps et startups techniques peuvent diagnostiquer et réparer les pannes réseau avec confiance et un risque minimal. Cette démarche s'intègre naturellement à vos pratiques autour de Node.js/Express, MongoDB, ou encore des intégrations Stripe et OpenAI API, tout en restant centrée sur la REST API connectivity et la sécurité opérationnelle.