Le protocole HTTP et les API REST

La requête HTTP

Les méthodes HTTP

La réponse HTTP et les codes de statut

• La réponse a la même structure : une ligne de statut (HTTP/1.1 200 OK), des en-têtes et un corps (le contenu).
• Le code de statut est un nombre à trois chiffres. Le premier chiffre indique la famille :

• Règle simple : 4xx = l'erreur vient du client (corriger la requête), 5xx = l'erreur vient du serveur (réessayer plus tard, prévenir l'administrateur).
• En-têtes de réponse courants : Content-Type (format du corps : text/html, application/json, image/png…), Content-Length (taille), Cache-Control (durée de mise en cache), Location (adresse de la ressource créée ou de la redirection), Set-Cookie, Access-Control-Allow-Origin (CORS).

7. JSON : le format des données

   • JSON (JavaScript Object Notation) est le format d'échange de données utilisé par presque toutes les API web. Il ressemble aux objets JavaScript, avec des règles plus strictes : clés entre guillemets doubles, pas de virgule finale, pas de commentaires, et seulement six types de valeurs (texte, nombre, booléen, null, tableau, objet).

   {
     "id": 42,
     "nom": "Ines Haddad",
     "groupe": "DEV-102",
     "moyenne": 14.5,
     "diplome": false,
     "modules": ["HTML", "CSS", "JavaScript"],
     "tuteur": { "nom": "M. Hajji", "email": "tuteur@centre.tn" },
     "telephone": null
   }

   • En JavaScript, deux fonctions font la conversion : JSON.stringify(objet) transforme un objet en texte JSON (pour l'envoyer), JSON.parse(texte) fait l'inverse (pour l'utiliser). Avec fetch, reponse.json() appelle JSON.parse pour vous.
   • Une date n'a pas de type JSON : on l'écrit en texte au format ISO 8601 ("2026-11-12T09:30:00Z").
   • Avant JSON, les échanges se faisaient en XML (d'où le X de « Ajax » et de « XMLHttpRequest ») : plus verbeux, plus lourd à lire en JavaScript. JSON l'a remplacé dans les API web dès les années 2010.

8. Qu'est-ce qu'une API REST ?

   • Une API (Application Programming Interface) est une porte d'entrée qu'un programme offre aux autres programmes. Une API web est une API accessible par HTTP : au lieu de renvoyer des pages HTML pour des humains, elle renvoie des données (en JSON) pour des programmes.
   • REST (REpresentational State Transfer), décrit par Roy Fielding en 2000, est un style d'organisation des API web, devenu la norme de fait. Ses principes :

   Principe	En pratique
   Tout est ressource, désignée par une URL	/stagiaires (la collection), /stagiaires/42 (un élément), /groupes/DEV-101/stagiaires (une sous-collection)
   Les méthodes HTTP indiquent l'action	Des noms dans l'URL, jamais des verbes : DELETE /stagiaires/42 et non GET /supprimerStagiaire?id=42
   Les codes de statut indiquent le résultat	201 après une création, 404 si l'élément n'existe pas, 422 si les données sont invalides
   Sans état	Chaque requête contient tout ce qu'il faut (dont le jeton d'authentification)
   Représentations	La même ressource peut être fournie en JSON, en XML, en CSV… selon l'en-tête Accept
   Réponses cachables	Le serveur indique combien de temps une réponse reste valable (Cache-Control)

   

   • Les quatre opérations de base sur des données, CRUD (Create, Read, Update, Delete), correspondent donc à POST, GET, PUT/PATCH et DELETE.
   • Bonnes pratiques d'URL : noms au pluriel, en minuscules avec des tirets (/sessions-examen), un numéro de version (/v1/) pour pouvoir faire évoluer l'API sans casser les applications existantes, des paramètres pour filtrer, trier et paginer (/stagiaires?groupe=DEV-101&tri=-moyenne&page=2).
   • Il existe d'autres styles d'API : GraphQL (une seule adresse, le client décrit exactement les données voulues), gRPC (entre serveurs, très rapide), les WebSockets (connexion permanente pour le temps réel : chat, notifications). REST reste le plus répandu et le plus simple à apprendre.

9. CORS : pourquoi une API peut refuser votre page

   • Par sécurité, le navigateur applique la politique de même origine: un script de http://127.0.0.1:5500 ne peut pas lire la réponse d'une requête vers https://api.autre-site.com… sauf si ce serveur l'autorise explicitement.
   • Cette autorisation s'appelle CORS (Cross-Origin Resource Sharing) : le serveur répond avec l'en-tête Access-Control-Allow-Origin: * (tout le monde) ou Access-Control-Allow-Origin: https://mon-site.tn (un site précis). Pour les requêtes « non simples » (PUT, DELETE, JSON envoyé…), le navigateur envoie d'abord une requête OPTIONS de vérification, dite preflight.
   • Si l'autorisation manque, la console affiche une erreur « blocked by CORS policy ». Ce n'est pas un bogue de votre code: seule la configuration du serveur peut le corriger. Les API publiques prévues pour le web (Open-Meteo, JSONPlaceholder…) envoient cet en-tête.

10. HTTP aujourd'hui : HTTP/2 et HTTP/3

    • HTTP/1.1 (1997) traite les requêtes une par une sur chaque connexion.
    • HTTP/2 (2015) fait passer de nombreuses requêtes en même temps sur une seule connexion et compresse les en-têtes.
    • HTTP/3 (normalisé en 2022) remplace TCP par QUIC, un transport plus rapide à établir et plus résistant aux réseaux mobiles instables. Il est utilisé par une large part des grands sites.
    • Pour vous, développeur, rien ne change : les méthodes, en-têtes et codes de statut restent les mêmes, et le navigateur choisit la version automatiquement (colonne Protocol de l'onglet Réseau : h2, h3).

11. Observer HTTP : l'onglet Réseau et curl

    • DevTools → Réseau (Network): ouvrez-le avant de charger la page. Chaque ligne est une requête ; cliquez dessus pour voir les onglets Headers (méthode, URL, statut, en-têtes), Payload (corps envoyé), Preview et Response (corps reçu), Timing (durée). Le filtre Fetch/XHR ne garde que les requêtes faites par JavaScript.
    • Clic droit sur une requête → Copy → Copy as fetch: DevTools écrit pour vous le code JavaScript équivalent. Copy as cURL donne la commande en ligne.
    • curl (installé avec Windows 10/11, macOS et Linux) envoie des requêtes depuis un terminal :

    # GET : afficher la réponse avec les en-têtes (-i)
    curl -i https://jsonplaceholder.typicode.com/users/1
    
    # POST avec un corps JSON
    curl -X POST https://jsonplaceholder.typicode.com/posts ^
      -H "Content-Type: application/json" ^
      -d "{\"title\": \"Bonjour\", \"userId\": 1}"
    # (sous Windows, ^ continue la ligne ; sous Linux et macOS, utilisez \)

    • Des outils graphiques comme Bruno, Insomnia ou Postman, ou l'extension REST Client de VS Code, permettent aussi de tester une API sans écrire de code.

12. Activités

Activité 1 : décortiquer des URL

• Pour l'URL https://www.google.com/search?q=formation+javascript&hl=fr#resultats, donnez le protocole, le domaine, le port utilisé, le chemin, les paramètres et l'ancre.
• Dans la console, utilisez new URL(...) pour vérifier vos réponses, puis ajoutez le paramètre page=2 avec url.searchParams.set() et affichez url.href.

Activité 2 : l'onglet Réseau

• Ouvrez l'onglet Réseau puis la page https://jsonplaceholder.typicode.com/users. Notez la méthode, le code de statut, le Content-Type de la réponse, sa taille et sa durée.
• Rechargez la page d'accueil d'un site d'information : combien de requêtes ? Quel est le type de fichier le plus fréquent ? Trouvez une requête de statut 304 ou servie depuis le cache.
• Demandez https://jsonplaceholder.typicode.com/users/9999: quel code obtenez-vous ?

Activité 3 : concevoir une API REST

• Le centre veut une API pour gérer ses formations et les inscriptions des stagiaires à ces formations. Écrivez, pour chaque besoin, la méthode et l'URL :
• lister les formations ; voir la formation 7 ; créer une formation ; changer seulement la durée de la formation 7 ; supprimer la formation 7 ; lister les inscrits de la formation 7 ; inscrire le stagiaire 42 à la formation 7 ; lister les formations de niveau BTS, triées par date de début.
• Pour chacune, indiquez le code de statut attendu en cas de succès.

Activité 4 : quel code de statut ?

• Associez un code à chaque situation : le jeton de connexion a expiré ; la note envoyée vaut 25 ; le stagiaire demandé n'existe pas ; le serveur de base de données est en panne ; l'utilisateur a envoyé 500 requêtes en une minute ; un formateur veut modifier les notes d'un groupe qui n'est pas le sien ; la suppression a réussi.

À retenir

• HTTP : le client envoie une requête (méthode, URL, en-têtes, corps), le serveur renvoie une réponse (statut, en-têtes, corps). HTTPS la chiffre.
• Méthodes : GET lire, POST créer, PUT remplacer, PATCH modifier, DELETE supprimer.
• Statuts : 2xx succès, 3xx redirection, 4xx erreur du client, 5xx erreur du serveur.
• Une API REST expose des ressources (URL au pluriel) manipulées avec les méthodes HTTP et échange des données en JSON ; CORS décide si une page d'un autre site peut lire ses réponses.

Sources : MDN Web Docs, WHATWG (XMLHttpRequest, Fetch), IETF, open-meteo.com.