Examiner une requête

Ce que vous saurez faire

Voyez exactement ce qu’un client a envoyé et ce que le serveur a répondu. Utilisez deux outils toujours accessibles : les outils de développement du navigateur et curl. Quand une API « ne fonctionne pas », c’est la première chose à vérifier.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 35 minutes

Ce que vous devez savoir

• Les parties d’une requête et d’une réponse, présentées dans Les bases de HTTP : une requête, partie par partie et Les bases de HTTP : codes d’état.
• Les étapes d’une requête, présentées dans Du navigateur au serveur : les bases : le trajet complet. curl les montre dans cette leçon.

Ce qu’il vous faut sur votre ordinateur

• Un navigateur de bureau : Chrome, Edge ou Firefox. Safari fonctionne aussi, après l’activation de Settings › Advanced › Show features for web developers (réglages › avancés › afficher les fonctionnalités pour les développeurs Web).
• curl. Il est inclus dans macOS, Windows 10 et 11, et la plupart des systèmes Linux. Sur Windows, tapez curl.exe (voir ci-dessous).
• Une connexion Internet. Les exemples utilisent Postman Echo et le fichier de données public du cours.

Testé avec curl 8,7 sur macOS et Chrome 141.

Les outils de développement du navigateur

Chaque navigateur de bureau possède des outils de développement : un panneau qui montre ce que fait une page. L’onglet Network (réseau) liste toutes les requêtes de la page, avec leur requête et leur réponse complètes.

1. Ouvrez un nouvel onglet du navigateur.
2. Ouvrez les outils de développement : appuyez sur F12, ou Cmd+Option+I sur macOS. Sélectionnez l’onglet Network.
3. Dans la barre d’adresse, ouvrez https://raw.githubusercontent.com/Nextia-Intelligence/nextia-learning-labs/main/C02/data/tickets.json.
4. Dans l’onglet Network, sélectionnez la ligne tickets.json.
5. Regardez Headers (en-têtes). Trouvez la méthode de requête (GET), le code d’état (200) et l’en-tête de réponse content-type (type de contenu).
6. Regardez Response (réponse) ou Preview (aperçu). Vous y verrez le corps : les 15 billets de soutien.

Les outils de développement montrent les requêtes du navigateur. Ils conviennent le mieux quand une page Web utilise votre API : vous voyez la requête exactement comme la page l’envoie. Pour envoyer une requête que vous concevez, utilisez curl.

curl

curl envoie une requête depuis le terminal et affiche la réponse. Chaque partie de la requête correspond à une option :

Option	Signification
-i	Afficher les en-têtes de réponse, pas seulement le corps.
-v	Tout afficher : DNS, connexion, TLS, en-têtes de requête et en-têtes de réponse.
-X POST	Utiliser cette méthode. Sans cette option, curl utilise GET.
-H "Name: value"	Ajouter un en-tête de requête.
--data @file.json	Envoyer le contenu de ce fichier comme corps.
-s	Mode silencieux : aucune barre de progression.

Windows : tapez curl.exe

Dans Windows PowerShell, curl est une autre commande, avec d’autres options. Tapez plutôt curl.exe dans chaque commande de ce cours. De plus, Windows PowerShell modifie les guillemets du JSON que vous tapez dans une commande. Ce cours envoie donc toujours le JSON depuis un fichier, avec --data @file.json. Cela fonctionne de la même façon sur chaque système.

Exemple détaillé : une requête et sa réponse

Amira envoie une requête GET et affiche les en-têtes de réponse avec -i :

Terminal (on Windows: curl.exe)

curl -i "https://postman-echo.com/get?status=open"

Sortie (abrégée)

HTTP/2 200
content-type: application/json; charset=utf-8
content-length: 231
server: cloudflare

{"args":{"status":"open"},"headers":{"host":"postman-echo.com","accept":"*/*","user-agent":"curl/8.7.1",...},"url":"https://postman-echo.com/get?status=open"}

Lisez depuis le haut : le protocole et le code d’état (HTTP/2 200), les en-têtes de réponse, une ligne vide, puis le corps. Le corps renvoyé par Postman Echo montre ce qu’il a reçu : le paramètre de requête et les en-têtes ajoutés par curl (accept, user-agent).

Elle envoie ensuite une requête POST avec un corps JSON. Elle enregistre d’abord le corps dans un fichier, ticket.json :

ticket.json

{"subject": "Charged twice for March", "body": "Same invoice two times."}

Terminal (on Windows: curl.exe)

curl -i -X POST https://postman-echo.com/post -H "Content-Type: application/json" --data @ticket.json

Sortie (abrégée)

HTTP/2 200
content-type: application/json; charset=utf-8

{"data":{"subject":"Charged twice for March","body":"Same invoice two times."},"headers":{"content-type":"application/json",...},"json":{"subject":"Charged twice for March","body":"Same invoice two times."},...}

Le champ json montre que le serveur a lu le corps comme du JSON, grâce à l’en-tête Content-Type.

Voir chaque étape avec -v

-v (mode détaillé) montre les étapes de Du navigateur au serveur : les bases. Les lignes commençant par * sont les notes de curl. > indique ce que curl a envoyé, et <, ce qu’il a reçu. Ici, Postman Echo renvoie volontairement un code 503 :

Terminal (on Windows: curl.exe)

curl -v https://postman-echo.com/status/503

Output (the important lines)

* Host postman-echo.com:443 was resolved.
* Connected to postman-echo.com (162.159.142.41) port 443
* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256
> GET /status/503 HTTP/2
> Host: postman-echo.com
< HTTP/2 503
< content-type: application/json; charset=utf-8
{"status":503}

Le DNS a fonctionné (was resolved, « a été résolu »). La connexion a fonctionné (Connected ... port 443, « connecté … port 443 »). TLS a fonctionné (SSL connection using TLSv1.3, « connexion SSL utilisant TLSv1.3 »), et la requête a été envoyée. Le serveur a répondu avec 503. Le réseau a entièrement fonctionné. L’application a signalé un problème. C’est la distinction la plus importante de ce module.

Exercice guidé : examiner deux requêtes

1. Créez un dossier pour les fichiers d’exercice de ce module, puis placez-vous dans ce dossier :

   mkdir -p ~/projects/http-practice
   cd ~/projects/http-practice

   Sur Windows, mkdir ~/projects/http-practice fonctionne sans -p.

2. Créez ticket.json avec le corps de l’exemple détaillé.

3. Envoyez-le avec curl -i -X POST, comme dans l’exemple détaillé. Trouvez le code d’état, l’en-tête content-type et le champ json dans le corps.

4. Envoyez la même requête sans l’option -H "Content-Type: application/json". Comparez la réponse. Quel en-tête curl a-t-il envoyé à la place? (Regardez le champ headers du corps.)

5. Exécutez curl -v https://postman-echo.com/status/404. Trouvez la ligne qui montre la connexion, celle qui montre la requête et celle qui contient le code d’état.

Afficher ce que vous devriez voir à l’étape 4

Sans votre en-tête, curl envoie content-type: application/x-www-form-urlencoded, le format d’un formulaire HTML. Postman Echo lit donc le corps comme un formulaire. Dans le champ form, tout le texte JSON devient le nom d’un seul champ, avec une valeur vide. Le serveur a suivi les indications de l’en-tête. L’API que vous créez répond 422 à la même requête. Envoyez toujours l’en-tête Content-Type avec un corps.

À vous : lire une réponse que vous n’avez pas conçue

Ouvrez les outils de développement sur une page Web que vous utilisez souvent, puis rechargez la page. Trouvez une requête dont la réponse est en JSON (la colonne Type affiche fetch, xhr ou json). Pour cette requête, notez :

1. La méthode, l’hôte et le chemin.
2. Deux en-têtes de requête et, selon vous, le rôle de chacun.
3. Le code d’état et le content-type de la réponse.
4. Un champ du corps de la réponse et, selon vous, sa signification.

Il n’y a pas une seule bonne réponse. Le but est de lire une vraie requête partie par partie, comme vous lirez celles de votre propre API.

Erreur courante

Une connexion réussie avec une erreur d'application

Symptôme : une requête « échoue », et vous commencez à vérifier la connexion Internet, le pare-feu ou le DNS. Mais curl affiche un code d’état, comme 404, 422 ou 500.

Cause : tout code d’état prouve que le DNS, la connexion et TLS ont fonctionné, et que l’application a répondu. Le problème vient de la requête (code 4xx) ou de l’application (code 5xx), pas du réseau.

Solution :

1. Exécutez la requête avec curl -v. Si vous voyez une ligne < HTTP/... avec un code d’état, le réseau fonctionne.
2. Pour un code 4xx, lisez le corps de la réponse. Une bonne API explique ce qui ne va pas dans la requête.
3. Pour un code 5xx, lisez les journaux (logs) de l’application. Le client ne peut pas corriger le problème.
4. Vérifiez l’URL, le réseau et le serveur seulement s’il n’y a aucun code d’état. Exemples : Could not resolve host (impossible de résoudre l’hôte), Couldn't connect to server (impossible de se connecter au serveur), un délai dépassé ou une erreur SSL.

Vérifiez votre compréhension

Vérification du module : curl -v affiche « Connected to api.example.com port 443 », une ligne TLS, puis « < HTTP/2 500 ». Expliquez pourquoi la connexion réseau a fonctionné, mais la requête a quand même échoué, et qui doit corriger le problème.

Afficher la réponse

Les lignes de connexion et de TLS montrent que le DNS, la connexion et le chiffrement ont tous fonctionné. Le serveur a reçu la requête. 500 est la réponse de l’application : elle a rencontré une erreur inattendue pendant le traitement de la requête. Le réseau fonctionne, et renvoyer la même requête n’aide généralement pas. Les responsables de l’API doivent corriger le problème à l’aide de ses journaux. Avec 503, une tentative ultérieure pourrait fonctionner. Avec un code 4xx, le client devrait modifier la requête.

Vérifiez votre compréhension

Pourquoi ce cours envoie-t-il les corps JSON depuis un fichier avec --data @ticket.json, plutôt que de taper le JSON dans la commande?

Afficher la réponse

Taper du JSON dans une commande dépend des règles de guillemets de l’interpréteur de commandes. Windows PowerShell modifie ces guillemets avant que curl les reçoive. Un fichier évite complètement l’interpréteur de commandes. La même commande fonctionne donc sur macOS, Linux et Windows. Le fichier est aussi facile à lire, à modifier et à conserver avec le projet.

Récapitulatif

• L’onglet Network des outils de développement montre chaque requête d’une page, avec ses en-têtes et son corps.
• curl envoie une requête que vous concevez : -i affiche les en-têtes de réponse, -v affiche chaque étape. -X, -H et --data @file.json construisent la requête. Sur Windows, tapez curl.exe.
• Un code d’état signifie que le réseau a fonctionné et que l’application a répondu. Sans code d’état, la panne vient de l’URL, du réseau ou du serveur.

Vous pouvez maintenant lire toute requête et toute réponse. Dans le prochain module, vous créez le côté serveur : un service FastAPI.

Leçon suivante : Environnement et premier point de terminaison