Du navigateur au serveur : les bases

Ce que vous saurez faire

Comprenez ce qui se passe entre « envoyer une requête à une URL » et « mon code la reçoit ». Quand une requête échoue, vous savez ainsi où chercher : dans l’adresse, le réseau, la connexion ou l’application.

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

Ce que vous devez savoir

• Vous avez terminé Python pour l’ingénierie de l’IA en pratique, ou vous savez utiliser un terminal, un environnement virtuel et httpx. Utiliser un client HTTP simple : Requête et réponse a présenté les requêtes, les réponses et les codes d’état. Ce module explique ce qui se passe en chemin.

Ce qu’il vous faut sur votre ordinateur

• Rien. Vous n’installez et n’exécutez rien dans cette leçon.

Clients et serveurs

Sur le Web, un client est un programme qui demande quelque chose. Un serveur est un programme qui répond. Votre navigateur est un client. C’est aussi le cas de curl, de Postman et d’un programme Python qui utilise httpx. L’API que vous créez dans ce cours est un serveur : elle attend des requêtes et répond à chacune.

Le client et le serveur communiquent avec HTTP (Hypertext Transfer Protocol, protocole de transfert hypertexte). Ces règles définissent le texte d’une requête et d’une réponse. Chaque échange commence par le client. Un serveur n’envoie jamais rien que personne n’a demandé.

Les parties d’une URL

Une URL (Uniform Resource Locator, localisateur uniforme de ressource) est l’adresse d’une ressource, comme une page Web ou un point de terminaison d’API. Voici une URL à laquelle l’API de ce cours répondra :

https://api.example.com:443/v1/classify?lang=en

Partie	Valeur	Signification
Schéma	https	Comment communiquer avec le serveur. https est HTTP avec chiffrement. http n’utilise pas de chiffrement.
Hôte	api.example.com	Le nom du serveur.
Port	443	Quel programme sur ce serveur. Souvent omis : https signifie 443, et http signifie 80.
Chemin	/v1/classify	Quelle ressource sur le serveur.
Paramètres de requête	lang=en	Des valeurs supplémentaires, après ?, sous forme de paires name=value reliées par &.

Python peut séparer une URL en ces parties. Essayez avec vos propres URL :

Exécutez du Python dans votre navigateur

Séparer une URL en ses parties

Remplacez l’URL par http://localhost:8000/health, puis exécutez le code de nouveau. Quelle partie vaut maintenant None (aucune valeur), et pourquoi?

Code Python (vous pouvez le modifier)from urllib.parse import parse_qs, urlsplit url = "https://api.example.com:443/v1/classify?lang=en&limit=5" parts = urlsplit(url) print("scheme:", parts.scheme) print("host: ", parts.hostname) print("port: ", parts.port) print("path: ", parts.path) print("query: ", parse_qs(parts.query))

Du nom au serveur : DNS

Un ordinateur sur Internet possède une adresse IP, un nombre comme 185.199.109.133. Les gens utilisent des noms, comme raw.githubusercontent.com, parce qu’ils sont plus faciles à retenir. Ces noms peuvent rester les mêmes quand les nombres changent.

DNS (Domain Name System, système de noms de domaine) transforme un nom en adresse IP. Avant de se connecter, le client pose une question à un serveur DNS. La question est : « Quelle est l’adresse IP de raw.githubusercontent.com? » La réponse reste en cache pendant un certain temps. La prochaine requête n’a donc pas besoin de poser la question de nouveau.

Le nom localhost est particulier. Il signifie toujours « cet ordinateur » et n’a pas besoin de DNS. Son adresse IP est 127.0.0.1. Quand vous exécutez votre API sur votre ordinateur, l’URL est http://localhost:8000 ou http://127.0.0.1:8000.

Ports : quel programme

Un ordinateur serveur peut exécuter plusieurs programmes qui répondent aux requêtes : un serveur Web, une base de données, votre API. Un port est un nombre de 1 à 65 535 qui sélectionne l’un d’eux. Un programme écoute sur un port. Le système d’exploitation lui transmet chaque connexion à ce port.

Port	Utilisation habituelle
443	HTTPS
80	HTTP
8000	Un serveur de développement sur votre ordinateur, comme l’API de ce cours

Un seul programme peut écouter sur un port à la fois. Si un deuxième programme essaie, il reçoit une erreur comme address already in use (adresse déjà utilisée). Vous rencontrerez cette erreur dans le prochain module.

HTTPS : TLS protège la confidentialité des échanges

Avec http, chaque requête et chaque réponse circulent en texte clair. Tout ordinateur en chemin, comme un routeur Wi-Fi public, peut les lire, y compris les mots de passe et les clés d’API.

HTTPS est HTTP dans une connexion TLS (Transport Layer Security, sécurité de la couche transport). Avant la première requête, le client et le serveur font deux choses :

1. Le serveur présente un certificat : un document signé qui prouve qu’il est bien api.example.com. Le client vérifie la signature et s’arrête si elle ne correspond pas.
2. Ils choisissent ensemble des clés pour chiffrer tout ce qui suit. Les ordinateurs en chemin peuvent voir que vous communiquez avec le serveur, mais pas le contenu des échanges.

Utilisez https pour toute API sur Internet. http convient seulement à localhost, où la requête ne quitte jamais votre ordinateur.

Le trajet complet

Une requête à une API HTTPS : DNS, connexion, TLS, puis HTTP. Votre code voit seulement les étapes 6 et 7.

Description textuelle du diagramme

1. Le client demande à DNS l’adresse IP de api.example.com.
2. DNS répond 203.0.113.10.
3. Le client se connecte à cette adresse, sur le port 443.
4. TLS : le client vérifie le certificat du serveur, puis ils choisissent ensemble le chiffrement.
5. Le client envoie la requête HTTP : la méthode et le chemin POST /v1/classify, les en-têtes et un corps JSON.
6. Le serveur transmet la requête à l’application, qui est votre API.
7. L’application renvoie un code d’état, des en-têtes et un corps JSON.
8. Le serveur envoie cette réponse HTTP au client.

Chaque étape peut échouer, et chaque échec se présente différemment. Voici le point le plus utile à retenir de cette leçon :

Étape de l’échec	Ce que voit le client	Où chercher
1–2 DNS	Could not resolve host (impossible de résoudre le nom d’hôte), nodename nor servname provided (nom de nœud ou de service non fourni)	Le nom d’hôte dans l’URL.
3 Connexion	Couldn't connect to server (connexion au serveur impossible), Connection refused (connexion refusée), ou un délai dépassé	Le serveur fonctionne-t-il? Le port est-il correct?
4 TLS	certificate verify failed (échec de la vérification du certificat), erreurs SSL	Le certificat, ou une confusion entre http et https.
6–7 Application	Une réponse avec un code d’état 4xx ou 5xx	La requête, ou le code et les journaux (logs) de l’application.

Les étapes 1 à 4 échouent avant que votre application voie quoi que ce soit. Ses journaux ne contiennent donc rien. Les étapes 6 et 7 donnent une vraie réponse HTTP. La connexion a fonctionné, et l’application a dit non.

Les études de cas à la fin du cours

Les leçons vous font créer une petite API étape par étape. Le cours se termine par deux études de cas : des projets complets qui utilisent des données réelles. Vous partez d’un dossier vide pour obtenir une API testée, documentée et déployée. Vous téléchargez un projet de départ, suivez les étapes dans VS Code et comparez votre travail à une version terminée.

Études de cas de ce cours

À la fin du cours, vous appliquez ce que vous avez appris à un projet réaliste, des données jusqu’à la recommandation. Terminez-en au moins une pour obtenir le certificat; les autres sont facultatives.

• Servir un modèle de prix des maisonsPlacer un modèle déjà prêt derrière une API d'estimation validée, testée, documentée et déployée.
• Créer une API de données sur les demandes de service municipalUne API en lecture seule sur une vraie base de données : filtres, pagination stable, statistiques quotidiennes, tests et étapes de déploiement.

Vous devez terminer au moins une étude de cas pour obtenir le certificat. Chacune est aussi un projet de portfolio que vous pouvez publier et présenter. Elles utilisent tout le cours. La plupart des personnes les commencent donc après le module 7.

Exercice guidé : identifier l’échec

Pour chaque message, indiquez à quelle étape la requête a échoué et quoi vérifier en premier. Comparez ensuite avec les réponses.

1. curl: (6) Could not resolve host: api.exmaple.com
2. curl: (7) Failed to connect to localhost port 8000 after 0 ms: Couldn't connect to server
3. Une réponse avec le code d’état 404 et le corps {"detail":"Not Found"}
4. ssl.SSLCertVerificationError: certificate verify failed: unable to get local issuer certificate
5. Une réponse avec le code d’état 503 et le corps {"error": {"code": "classifier_unavailable"}}

Afficher les réponses

1. DNS. Le nom d’hôte contient une faute de frappe : exmaple.
2. Connexion. Aucun programme n’écoute sur le port 8000 de cet ordinateur. Démarrez le serveur ou vérifiez le port.
3. Application. Le serveur a répondu, donc la connexion a fonctionné. Le chemin n’existe pas dans l’application.
4. TLS. Python ne peut pas vérifier le certificat. Sur macOS avec Python provenant de python.org, exécutez Install Certificates.command (installer les certificats), comme dans Installer et vérifier Python.
5. Application. L’API a fonctionné, mais un élément dont elle dépend n’a pas fonctionné. Le corps indique lequel.

Erreur courante

Confusion entre http et https

Symptôme : une requête à votre API locale échoue avec une erreur SSL, comme SSL: WRONG_VERSION_NUMBER (mauvais numéro de version). Ou une requête à une API publique renvoie une redirection ou une erreur.

Cause : le schéma ne correspond pas au protocole du serveur. Un serveur de développement sur votre ordinateur utilise http, sans chiffrement. Ainsi, https://localhost:8000 envoie du TLS à un programme qui ne le comprend pas. La plupart des API publiques utilisent seulement https.

Solution :

1. Pour votre ordinateur, utilisez http://localhost:8000 (ou http://127.0.0.1:8000).
2. Pour une API déployée, utilisez https://.
3. Copiez les URL depuis la documentation du service plutôt que de les saisir.

Vérifiez votre compréhension

Une requête reçoit une réponse avec le code d'état 500. DNS a-t-il fonctionné? La connexion a-t-elle fonctionné?

Afficher la réponse

Oui, les deux ont fonctionné. Un code d’état vient de l’application, à l’étape 7. Il ne peut exister que si DNS, la connexion et TLS ont tous fonctionné. Un code 500 signifie que l’application elle-même a rencontré une erreur. Consultez les journaux de l’application, pas le réseau.

Vérifiez votre compréhension

Pourquoi http://localhost:8000 convient-il pendant le développement, mais pas http://api.example.com pour une vraie API?

Afficher la réponse

Une requête à localhost ne quitte jamais votre ordinateur. Aucun autre ordinateur ne peut donc la lire. Une requête à api.example.com traverse plusieurs réseaux. Sans TLS, tout ordinateur en chemin peut la lire ou la modifier, y compris les clés d’API et les données personnelles.

Récapitulatif

• Un client demande, un serveur répond, et HTTP est le langage entre les deux.
• Une URL contient un schéma, un hôte, un port facultatif, un chemin et des paramètres de requête facultatifs.
• DNS transforme un nom d’hôte en adresse IP. localhost désigne toujours cet ordinateur.
• Un port sélectionne un programme sur le serveur. HTTPS (port 443) ajoute TLS : une vérification du certificat et du chiffrement.
• Les erreurs avant l’étape 6 viennent du réseau. Un code d’état vient de l’application.

Ensuite, vous examinerez le contenu des requêtes et des réponses : méthodes, en-têtes, paramètres, corps et codes d’état.

Leçon suivante : Les bases de HTTP