Cours HTTP et API REST — requêtes, codes d'état, en-têtes, cache, authentification, JSON, CORS et sécurité

Objectifs d'apprentissage

À la fin de ce cours, l'apprenant peut :

1. décrire le cycle requête/réponse HTTP et lire une requête et une réponse ;
2. choisir une méthode HTTP et un code d'état adaptés, et dire ce que signifient sûr et idempotent ;
3. lire les en-têtes courants (type de contenu, cache, cookies, autorisation) ;
4. situer HTTP/1.1, HTTP/2 et HTTP/3 en principe, et dire où intervient TLS ;
5. concevoir en principe une API REST : ressources, JSON, versionnement, pagination, erreurs normalisées ;
6. comparer clé d'API, Basic, jeton Bearer, OAuth 2.0 et OpenID Connect ;
7. expliquer CORS et la limitation de débit ;
8. observer un échange avec curl -v et filtrer du JSON avec jq, en lecture, sur un service jetable ;
9. citer les dix risques de l'OWASP API Security Top 10 (2023) et un réflexe de défense pour chacun.

Prérequis

• Savoir ouvrir Terminal et lire une commande avant de la valider (cours « Terminal macOS »).
• Notions de réseau : adresse, port, DNS, TCP (cours « Réseau », section Exploitation).
• Notions de chiffrement et de certificat (cours « Chiffrement et cryptographie »), utiles pour TLS.
• curl est livré avec macOS ; jq et python3 ne sont pas garantis : non vérifié (chapitre 11).

Parcours et chapitres

1. Le cycle requête/réponse

HTTP est un protocole sans état de type client/serveur : le client envoie une requête, le serveur renvoie une réponse. La RFC 9110 (« HTTP Semantics », STD 97, juin 2022) définit la sémantique commune à toutes les versions de HTTP (méthodes, codes d'état, en-têtes) ; chaque version a sa propre RFC pour la syntaxe sur le réseau (chapitre 5). Entre le client et le serveur peuvent se trouver des intermédiaires : proxy, proxy inverse, CDN, passerelle d'API.

Une requête comporte une ligne de requête (méthode, cible, version), des en-têtes et éventuellement un corps. Une réponse comporte un code d'état, des en-têtes et éventuellement un corps. Exemple de la forme générale (syntaxe HTTP/1.1, valeurs synthétiques) :

GET /v1/utilisateurs/42 HTTP/1.1
Host: api.example.test
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"id": 42, "nom": "demo"}

2. Méthodes HTTP, sûr et idempotent

La RFC 9110 définit les méthodes. Deux notions à retenir :

• sûre : la méthode ne sert qu'à lire, sans effet voulu sur le serveur ;
• idempotente : répéter la même requête plusieurs fois a le même effet qu'une seule.

PATCH est défini dans une RFC distincte (RFC 5789) qui n'a pas été relue pour ce cours : son caractère non idempotent par défaut est non vérifié ici. L'idempotence permet de rejouer sans risque une requête dont la réponse s'est perdue ; pour un POST, certaines API acceptent une clé d'idempotence envoyée en en-tête (convention d'API, pas une règle de la RFC 9110 : non vérifié).

3. Codes d'état

Le code d'état est un nombre à trois chiffres ; le premier donne la classe.

Points de vocabulaire utiles aux API :

• 401 Unauthorized : l'identification est absente ou invalide (malgré son nom, c'est un problème d'authentification) ; 403 Forbidden : le serveur sait qui vous êtes mais refuse (autorisation).
• 201 Created accompagne en général un en-tête Location désignant la nouvelle ressource ; 204 : succès sans corps.
• 409 Conflict : conflit avec l'état actuel de la ressource.
• 429 Too Many Requests : limitation de débit, définie par la RFC 6585 (avril 2012, avec 428, 431 et 511) ; sa réponse ne doit pas être mise en cache.
• 502, 503, 504 : le plus souvent un problème d'intermédiaire ou de disponibilité, pas du client.

Le statut exact de 422 (non défini par la RFC 9110 dans ses grandes lignes lues ici) et l'emploi précis de 418 sont non vérifiés ; en pratique les API utilisent 400 ou 422 pour une validation échouée : choix de conception, à fixer par équipe.

4. En-têtes courants et négociation de contenu

Les en-têtes sont des paires Nom: valeur, insensibles à la casse pour le nom. Ceux qu'il faut connaître :

La négociation de contenu permet au client d'annoncer ses préférences (Accept) et au serveur de répondre dans un format avec Content-Type. Un serveur qui reçoit un corps dans un format qu'il ne gère pas répond en général 415 ; un format de réponse non disponible, 406.

5. Versions du protocole : HTTP/1.1, HTTP/2 et HTTP/3

Les trois versions transportent la même sémantique (RFC 9110) mais pas de la même façon :

Pour le développeur d'API, la version est en général transparente : la même requête logique (méthode, chemin, en-têtes) s'écrit différemment sur le fil, mais le client et le serveur négocient la version. La RFC 9112 n'a pas été relue en détail ici (seule sa référence l'a été) : le détail de la syntaxe HTTP/1.1 est non vérifié.

TLS en renvoi. HTTPS est HTTP au-dessus de TLS : le chiffrement, le certificat du serveur et la vérification du nom sont traités dans le cours « Chiffrement et cryptographie ». Retenir seulement ici : toute API qui transporte un jeton ou des données personnelles doit être servie en HTTPS ; sur la boucle locale d'un exercice jetable, HTTP en clair est toléré parce que rien ne sort de la machine.

6. Cookies et sessions

Un cookie est un petit état que le serveur demande au client de conserver (Set-Cookie) et de renvoyer (Cookie). Il est défini par la RFC 6265 (avril 2011, Proposed Standard). Cette RFC a pu être mise à jour ou remplacée depuis : non vérifié. Attributs à connaître (décrits aussi sur MDN) :

• Secure : cookie envoyé seulement en HTTPS ;
• HttpOnly : inaccessible au JavaScript de la page ;
• SameSite : limite l'envoi dans les requêtes entre sites (réduit le CSRF) ;
• Max-Age / Expires : durée de vie ; Domain / Path : portée.

Les API appelées par des applications ou des scripts utilisent plutôt des jetons dans l'en-tête Authorization ; les cookies de session sont plutôt l'affaire des navigateurs. Un cookie de session est un secret au même titre qu'un mot de passe.

7. Cache

La RFC 9111 (« HTTP Caching », STD 98, juin 2022) décrit les caches privés (un seul utilisateur, le navigateur) et partagés (proxy, CDN). Notions clés :

• Cache-Control : max-age=N (durée de fraîcheur), no-store (ne rien stocker), no-cache (valider avant réutilisation), private / public ;
• validation : ETag (empreinte de version) ou Last-Modified ; le client renvoie If-None-Match / If-Modified-Since et le serveur répond 304 Not Modified sans corps si rien n'a changé ;
• Vary : liste les en-têtes de requête qui changent la réponse (par exemple Accept), pour ne pas servir la mauvaise variante.

8. REST : ressources, JSON et conventions

REST est un style d'architecture, pas un protocole : on expose des ressources identifiées par des URL (noms au pluriel : /v1/utilisateurs, /v1/utilisateurs/42) et on agit dessus avec les méthodes HTTP. La définition d'origine de REST (thèse de R. Fielding) n'a pas été consultée ici : ce cours présente les conventions courantes, qui varient d'une équipe à l'autre.

Conventions fréquentes :

JSON (RFC 8259, STD 90, décembre 2017) est le format d'échange courant : objets, tableaux, chaînes, nombres, booléens et null ; les textes échangés entre systèmes doivent être encodés en UTF-8. Exemple de ressource :

{
  "id": 42,
  "nom": "demo",
  "groupes": ["lecture", "support"],
  "actif": true
}

Versionnement. Une API évolue ; casser les clients existants est coûteux. Choix courants : version dans le chemin (/v1/…), dans un en-tête, ou dans le type de contenu. Aucun n'est imposé par une RFC lue ici (non vérifié) ; l'important est de ne pas changer le sens d'une version publiée, d'ajouter plutôt que retirer des champs, et d'annoncer la fin de vie d'une version.

Pagination. Une liste ne se renvoie pas en entier. Deux approches :

• par décalage : ?limite=50&decalage=100 (simple, mais lent et instable si les données changent) ;
• par curseur : ?apres=<CURSEUR> (stable et plus efficace sur de gros volumes).

La réponse indique la page suivante dans le corps ou dans l'en-tête Link (RFC 8288, non relue : non vérifié).

Erreurs normalisées. La RFC 9457 (« Problem Details for HTTP APIs », 2023, remplace la RFC 7807) définit un format JSON de description d'erreur, type de média application/problem+json, avec les champs type, title, status, detail et instance :

{
  "type": "https://api.example.test/erreurs/quota-depasse",
  "title": "Quota dépassé",
  "status": 429,
  "detail": "Trop de requêtes, réessayer plus tard."
}

Description d'API : OpenAPI. La spécification OpenAPI décrit une API HTTP dans un fichier (YAML ou JSON) : chemins, méthodes, paramètres, schémas, sécurité. La page spec.openapis.org/oas/latest.html indiquait, le 18 octobre 2026, la version 3.2.1 publiée le 10 septembre 2026 (lue par résumé : non vérifié pour le détail). Le fichier sert de contrat, de documentation et de base à des tests ou à la génération de clients.

9. Authentification des appels d'API

Distinguer deux notions : l'authentification (qui es-tu ?) et l'autorisation (qu'as-tu le droit de faire ?).

Encadré secrets.

OAuth 2.0 en principe. OAuth 2.0 est un cadre de délégation d'autorisation : une application (client) obtient d'un serveur d'autorisation un jeton d'accès, de portée (scope) et de durée limitées, qu'elle présente à l'API (serveur de ressources). La RFC 6749 (octobre 2012) définit quatre types d'octroi (code d'autorisation, implicite, mot de passe du propriétaire de la ressource, identifiants du client). La RFC 9700 (BCP 240, « Best Current Practice for OAuth 2.0 Security », 2025) met à jour ces recommandations : PKCE pour les clients publics, abandon de l'octroi implicite, interdiction de l'octroi par mot de passe, comparaison exacte des URI de redirection, jetons restreints à une audience. En pratique : privilégier le code d'autorisation avec PKCE pour une application avec utilisateur, et l'octroi identifiants du client pour un service qui agit en son nom propre.

OpenID Connect en principe. OpenID Connect Core 1.0 (avec l'erratum n° 2, 15 décembre 2023) ajoute à OAuth 2.0 la notion d'identité : le client reçoit un ID Token (un JWT) dont les champs obligatoires incluent iss (émetteur), sub (identifiant de l'utilisateur), aud (destinataire), exp (expiration) et iat (émission), plus nonce quand il a été demandé. Le client doit vérifier ces champs (et la signature). Ne pas confondre jeton d'identité (pour le client) et jeton d'accès (pour l'API).

Les JWT, leur validation précise et les mécanismes avancés (DPoP, mTLS, introspection) sont hors périmètre et non vérifiés ici ; voir aussi le cours « Annuaires et identités » pour SSO et SAML.

10. Limitation de débit

La limitation de débit (rate limiting) borne le nombre de requêtes qu'un client peut faire par période. Elle protège la disponibilité et limite les abus (essais de mots de passe, énumération, coût). Quand la limite est atteinte, le serveur répond 429 (RFC 6585), souvent avec Retry-After. Les en-têtes d'information du genre X-RateLimit-… sont des conventions de fournisseurs, non normalisées dans les sources lues : non vérifié.

Côté client, une bonne pratique est de réessayer avec un délai croissant (retrait exponentiel avec un peu d'aléa) et de ne jamais rejouer en boucle serrée. Côté serveur, appliquer la limite par clé, par adresse et par route sensible, au niveau du proxy ou de la passerelle d'API.

11. Observer un échange : curl et jq en lecture

curl envoie des requêtes ; -v montre la négociation, les en-têtes envoyés (>) et reçus (<). jq filtre du JSON. Options confirmées sur le manuel de curl 8.23.0 : -v, -i, -I, -s, -S, -H, -X, --json, -w, -o, --max-time, --fail-with-body, --resolve. Pour jq 1.8 : ., .cle, .[], select(…), et les options -r, -c, -e.

Préparation d'un service local jetable (dossier temporaire, boucle locale uniquement, quelques secondes) :

Attention, effet notable. Cette commande peut écrire ou écraser un fichier. Lire le contexte, les droits et l’effet attendu indiqués après le bloc ; ne jamais l’exécuter sur un système réel sans validation, d’abord dans un environnement de test.

DEMO="$(mktemp -d)"cd "$DEMO"printf '{"id": 42, "nom": "demo", "groupes": ["lecture", "support"]}\n' > utilisateur.jsonpython3 -m http.server 8080 --bind 127.0.0.1

• Contexte : Terminal macOS ; version de python3 inconnue (non vérifié : l'option --bind du module http.server n'a pas été relue sur la documentation de Python). Le service ne sert que des fichiers statiques : il imite GET et HEAD mais pas une vraie API (les autres méthodes reçoivent en général une erreur).
• Droits : utilisateur normal ; aucun sudo.
• Effet : crée un dossier temporaire et un fichier JSON, puis démarre un serveur sur 127.0.0.1:8080, tant que la commande tourne. Il écoute uniquement la boucle locale. Un autre terminal est nécessaire pour la suite.
• Vérification : dans un second terminal, curl -s http://127.0.0.1:8080/utilisateur.json renvoie le JSON.
• Retour arrière : arrêter le serveur avec Control-C, puis supprimer le dossier temporaire (cd ~ && rm -r "$DEMO" dans le terminal où DEMO est défini ; relire le chemin avant de valider).

Lectures, dans le second terminal :

curl -v http://127.0.0.1:8080/utilisateur.jsoncurl -sI http://127.0.0.1:8080/utilisateur.jsoncurl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/absent.jsoncurl -s http://127.0.0.1:8080/utilisateur.json | jq '.groupes[]'curl -s http://127.0.0.1:8080/utilisateur.json | jq -r '.nom'

• Contexte : Terminal ; curl 8.23.0 documenté, version installée non vérifiée ; jq à installer séparément si absent (installation non traitée ici).
• Droits : utilisateur normal.
• Effet : lecture seule, quelques requêtes vers la boucle locale. La première montre la connexion, les en-têtes envoyés et reçus ; la deuxième, seulement les en-têtes de réponse ; la troisième, le code d'état d'une ressource absente (404 attendu) ; les deux dernières extraient des champs JSON.
• Vérification : repérer GET, Host, Accept, 200 OK, Content-Type, Content-Length ; obtenir 404 pour la ressource absente ; lire "lecture" et "support", puis demo.
• Retour arrière : sans objet.

Pour viser le nom réservé example.test sans le résoudre (RFC 6761 réserve .test, non relue ici : non vérifié), --resolve force l'adresse :

curl -v --resolve api.example.test:8080:127.0.0.1 http://api.example.test:8080/utilisateur.json

• Contexte : Terminal ; le service jetable est démarré.
• Droits : utilisateur normal.
• Effet : lecture seule, une requête vers la boucle locale avec l'en-tête Host: api.example.test:8080 ; aucune résolution DNS réelle.
• Vérification : la ligne > Host: api.example.test:8080 apparaît.
• Retour arrière : sans objet.

12. CORS

Le navigateur applique la politique de même origine : un script chargé depuis une origine (schéma, domaine, port) ne peut pas lire librement les réponses d'une autre origine. CORS (Cross-Origin Resource Sharing) est le mécanisme, fondé sur des en-têtes HTTP, par lequel un serveur autorise des origines à le faire (MDN, page modifiée le 4 septembre 2026).

• Requête simple : GET, HEAD ou POST avec en-têtes et types de contenu « sûrs » : pas de contrôle préalable.
• Requête avec contrôle préalable (preflight) : le navigateur envoie d'abord OPTIONS avec Origin, Access-Control-Request-Method et Access-Control-Request-Headers ; le serveur répond avec Access-Control-Allow-Origin, -Methods, -Headers et éventuellement -Max-Age.
• Avec identifiants (cookies, autorisation), Access-Control-Allow-Origin ne peut pas valoir * : il faut nommer l'origine, et Access-Control-Allow-Credentials: true.

13. Sécurité des API : l'OWASP API Security Top 10 (2023)

L'OWASP API Security Top 10 — 2023 (api-security.owasp.org, ancienne adresse owasp.org/API-Security redirigée) liste dix risques. Vue d'ensemble, avec un réflexe de défense chacun :

Le détail de chaque risque, les exemples d'attaque et les mesures complètes sont sur le site de l'OWASP : seule la liste des intitulés a été lue pour ce cours ; les « défenses » ci-dessus sont des résumés de principe, à relire sur les pages de chaque risque avant validation.

Exercices et vérifications de fin de cours

Tous se font sur papier ou contre le service jetable du chapitre 11 (127.0.0.1), jamais contre une API réelle.

1. Lecture. Démarrer le service jetable, lancer curl -v sur utilisateur.json, entourer la ligne de requête, deux en-têtes envoyés, le code d'état et deux en-têtes reçus.
2. Méthodes. Pour chaque opération (lister, créer, remplacer, supprimer), donner méthode, chemin REST, code de succès attendu, et dire si on peut la rejouer sans risque.
3. Codes. Associer un code d'état à ces cas : ressource absente, jeton expiré, droits insuffisants, trop de requêtes, serveur en panne.
4. Cache. Pour une liste personnelle d'utilisateur, écrire l'en-tête Cache-Control adapté et expliquer pourquoi.
5. JSON. Avec jq, extraire le premier groupe, puis tous les groupes sous forme de lignes de texte (-r).
6. Erreur. Écrire une réponse application/problem+json pour un 404.
7. Authentification. Dire pourquoi un jeton ne doit pas être placé dans l'URL, et citer deux autres endroits où il ne doit pas apparaître.
8. CORS. Expliquer pourquoi curl n'est pas bloqué par CORS alors qu'un navigateur l'est.
9. OWASP. Pour GET /v1/factures/123, décrire un scénario API1 et la vérification qui l'empêche.
10. Limitation. Décrire la réponse d'un serveur à un client trop rapide et la stratégie de reprise du client.

Critères de réussite

• Lire une requête et une réponse et dire ce qui s'est passé.
• Choisir méthode, code d'état et corps d'erreur cohérents.
• Ne jamais exposer un secret (URL, journal, capture, dépôt).
• Ne tester que sur un service local jetable ou example.test.
• Dire ce qui n'est pas vérifié (voir plus bas).