1. Des ressources
Chaque ressource a une adresse : /users pour la collection, /users/42 pour un élément.
Informatique · Web et réseaux
Ouvrir une page, lancer une appli : ton appareil envoie un petit texte, le serveur répond. Ces règles s'appellent HTTP.
Déjà à l'aise ? Aller au quizLe principe
Quand tu ouvres une page, ton navigateur écrit un message au serveur. Celui-ci répond avec un autre message, qui contient la page.
Les API REST s'en servent pour que des programmes se parlent.
Après cette fiche, tu sais
Une seule, peut-être ? Ou plusieurs ?
Une question, une réponse
Notion 1 · Le dialogue client-serveur
HTTP (HyperText Transfer Protocol) fixe la forme et le sens de deux messages : la requête, envoyée par un client, et la réponse, renvoyée par un serveur.
Le client peut être un navigateur, une appli mobile, un programme ou Postman ; le serveur, un site web ou une API, un service fait pour être appelé par des programmes.
Sans état : chaque requête HTTP se comprend toute seule, sans dépendre des précédentes.
Pour se souvenir de toi d'une page à l'autre (panier, connexion), un site ajoute un état avec des cookies ou des jetons, envoyés à chaque requête.
HTTP ne transporte rien lui-même : il s'appuie sur TCP (ou sur QUIC pour HTTP/3), et TLS chiffre les échanges en HTTPS. La fiche Réseaux détaille ces couches ; ici, on s'intéresse aux messages.
Fais défiler : cinq requêtes partent l'une après l'autre, et chaque réponse revient avec son code d'état. Tu peux aussi toucher une requête pour la revoir.
Chaque requête reçoit une réponse
requête GET /usersréponse …
Même quand la page n'existe pas ?
Tout tient dans du texte
Notion 2 · Anatomie d'un message
En HTTP/1.1, requête et réponse sont de simples lignes de texte, avec la même structure : une ligne de départ, des en-têtes (une paire Nom: valeur par ligne), une ligne vide, puis un corps facultatif.3
Les en-têtes décrivent le message : qui le reçoit, dans quel format, de quelle taille.
Le même sens, dans toutes les versions.
HTTP/2 et HTTP/3 emballent ces messages en binaire pour aller plus vite, mais leur sens reste le même : ce que tu lis ici vaut pour toutes les versions.
Fais défiler : une vraie requête s'éclate en morceaux, puis sa réponse.
Voici une vraie requête : trois lignes de texte, puis une ligne vide. Ton navigateur en écrit une à chaque clic.
La méthode (GET : lire), la cible (la ressource voulue) et la version du protocole.
Un par ligne. Host nomme le site visé ; Accept annonce les formats que le client sait lire.
Elle termine les en-têtes. Un GET n'envoie pas de corps : la requête s'arrête là.
La réponse commence par la version, le code d'état (200) et sa raison (OK) : réussite.
Ils décrivent le corps : son format (Content-Type) et sa taille en octets (Content-Length : 32).
Après la ligne vide : la fiche 42 en JSON. C'est une représentation de la ressource, pas la ressource elle-même.
Et les autres en-têtes, alors ?
Attention aux octets
Content-Length compte des octets. En UTF-8, les lettres accentuées en prennent deux : le corps {"ville":"Genève"} fait 18 caractères, mais 19 octets.
Ton appli veut créer Zoé. Les six lignes de sa requête ont été mélangées : touche une ligne, puis celle avec laquelle l'échanger.
Que demande le client ?
Notion 3 · Les méthodes
La méthode dit ce que le client demande de faire à la ressource. Les cinq qu'on utilise tous les jours correspondent aux opérations CRUD : Create (POST), Read (GET), Update (PUT ou PATCH), Delete (DELETE).
Méthode sûre : elle ne demande aucune modification sur le serveur, lecture seule. GET, HEAD et OPTIONS sont sûres.
Méthode idempotente : envoyer la même requête deux, trois ou dix fois a le même effet sur le serveur qu'un seul envoi. PUT, DELETE et toutes les méthodes sûres le sont.
Fais défiler : POST, puis PUT, puis DELETE sont envoyés une, deux, trois fois de suite. Surveille la table du serveur, pas seulement les codes.
Répéter, est-ce recommencer ?
méthode POSTenvois 0utilisateurs 2
Retiens le DELETE.
Le deuxième envoi répond 404, et pourtant DELETE est idempotent. L'idempotence parle de l'effet sur le serveur, pas du code reçu.
Touche une méthode, puis la case qui lui correspond. Une méthode sûre est toujours aussi idempotente.
Le premier chiffre parle
Notion 4 · Les codes d'état
Chaque réponse commence par un code à trois chiffres. Le premier chiffre donne la famille : même face à un code inconnu, tu sais déjà de quel côté est le problème.1
Les cinq familles
1xx : la requête est reçue, le traitement continue.
2xx : réussite. La requête a été reçue, comprise et acceptée.
200 OK : le résultat, par exemple la ressource lue.201 Created : une ressource a été créée ; son adresse est en général dans l'en-tête Location.204 No Content : rien à renvoyer, fréquent après un DELETE.3xx : redirection. Le client doit faire autre chose, par exemple aller à une autre adresse.
301 Moved Permanently : la ressource a une nouvelle adresse définitive.304 Not Modified : le client a déjà la version à jour dans son cache, inutile de la renvoyer.4xx : erreur du client. La requête est mal formée, non autorisée ou vise une ressource absente.
400 Bad Request : requête incorrecte, JSON invalide ou champ obligatoire manquant.404 Not Found : aucune ressource à cette adresse.405 Method Not Allowed : méthode non permise sur cette ressource ; l'en-tête Allow liste les méthodes permises.4xx · suite
409 Conflict : conflit avec l'état de la ressource, par exemple deux modifications concurrentes.429 Too Many Requests : trop de requêtes en peu de temps, la limite de débit est dépassée.8Piège
Le nom anglais de 401, « Unauthorized », trompe : il s'agit d'authentification (qui es-tu ?). 403 concerne l'autorisation (as-tu le droit ?) : le serveur sait qui tu es, et dit non.
5xx : erreur du serveur. La requête semblait correcte, mais le serveur n'a pas pu la traiter.
500 Internal Server Error : erreur inattendue du serveur, une exception non prévue par exemple.503 Service Unavailable : service momentanément indisponible, par surcharge ou maintenance.Huit situations d'une appli de classe. Choisis le code que le serveur devrait renvoyer.
Des noms, pas des verbes
Notion 5 · REST
REST (Representational State Transfer) est un style d'architecture décrit par Roy Fielding dans sa thèse de doctorat, en 2000.5 Ce n'est ni un protocole ni une bibliothèque : ce sont des contraintes. Une API qui les respecte est dite RESTful.
Une ressource est identifiée par une adresse, comme /users/42. On la manipule à travers des représentations, le plus souvent du JSON.
Chaque ressource a une adresse : /users pour la collection, /users/42 pour un élément.
On manipule une représentation de la ressource, le plus souvent du JSON.
Les méthodes HTTP gardent leur sens standard, les codes aussi.
Chaque requête contient tout ce qu'il faut pour la comprendre, jeton d'authentification compris.
Une réponse indique si on peut la garder en cache. Le client ne sait pas s'il parle au serveur final ou à un intermédiaire.
En pratique
La méthode dit quoi faire, l'adresse dit à quoi.
Des adresses bien construites
Des noms, pas des verbes : la méthode dit déjà l'action. DELETE /users/42, et non GET /supprimerUser?id=42.
Des collections au pluriel et une hiérarchie quand elle a du sens : /users/42/commandes. Les filtres, le tri et la pagination vont dans la partie requête : /users?role=admin&page=2.
Fais défiler : chaque morceau de l'adresse s'allume, avec ce qu'il devient dans la requête envoyée. Tu peux aussi toucher un morceau.
Le chemin
Une API de démonstration tourne dans ta page : rien ne part sur Internet. Choisis la méthode, écris le chemin et, si besoin, le corps JSON, puis envoie. La réponse s'affiche comme un vrai message HTTP.
Lire la liste
Affiche la liste de tous les utilisateurs.
(aucune requête envoyée)
[]
0 mission réussie sur 6
Qui a le droit de lire ?
Notion 6 · En-têtes et CORS
Les noms d'en-têtes ne tiennent pas compte des majuscules : content-type et Content-Type désignent le même champ.
Le format du corps envoyé : application/json, text/html…
Les formats que le client sait lire.
Les identifiants du client, par exemple Bearer suivi d'un jeton.
Les règles de mise en cache : max-age=60, no-store.
L'adresse de la ressource créée (201) ou de la redirection (3xx).
Le serveur dépose un cookie, le navigateur le renvoie ensuite.
Une origine, c'est le trio schéma, hôte et port : https://app.example et https://api.example sont deux origines différentes.
Envoyer n'est pas lire.
Le navigateur applique la politique de même origine : le script d'une page peut envoyer des requêtes vers une autre origine, mais il ne peut pas lire leurs réponses.7
CORS (Cross-Origin Resource Sharing) : un mécanisme fondé sur des en-têtes HTTP, qui permet à un serveur d'indiquer quelles autres origines le navigateur doit autoriser.4
L'en-tête clé est Access-Control-Allow-Origin.
Une requête est dite « simple » si sa méthode est GET, HEAD ou POST, sans en-tête personnalisé, et avec un Content-Type parmi application/x-www-form-urlencoded, multipart/form-data et text/plain. Pour toutes les autres, le navigateur demande d'abord la permission.
Fais défiler : le navigateur demande d'abord la permission pour le PUT, puis le GET simple part sans question.
Le script d'une page de https://app.example veut modifier une note sur https://api.example. Autre origine : le navigateur applique CORS.
Un PUT avec du JSON n'est pas une requête simple. Le navigateur envoie d'abord, tout seul, une requête OPTIONS pour demander la permission.
Le serveur accepte : il nomme l'origine autorisée, les méthodes et les en-têtes permis.
Le navigateur envoie alors le PUT. La réponse porte encore Access-Control-Allow-Origin : le script peut la lire.
Sans ces en-têtes, le PUT ne part pas. Le script reçoit une erreur sans détail : l'explication n'est que dans la console.
Un GET simple part sans question : le serveur le reçoit et le traite. Sans le bon en-tête, seule la lecture de la réponse est bloquée.
CORS protège la personne, pas le serveur.
curl ou Postman ne l'appliquent pas. Une API doit donc toujours vérifier elle-même qui l'appelle et avec quels droits.
Versions et HTTPS
HTTPS, c'est HTTP dans une connexion chiffrée par TLS : personne sur le trajet ne peut lire ni modifier les messages, et un certificat prouve l'identité du serveur. Port par défaut : 443 (80 pour HTTP).
HTTP/3, normalisé en 20226. Méthodes, en-têtes et codes restent identiques d'une version à l'autre.
Six pièges à éviter
Attention
Six erreurs qu'on voit partout, une par carte.
PUT remplace toute la ressource. Envoyer {"role":"admin"} en PUT peut effacer le nom et les autres champs ; pour ne changer qu'un champ, c'est PATCH.
Un lien « supprimer » en GET est dangereux : un robot ou un outil de préchargement qui suit les liens déclencherait la suppression. GET doit rester en lecture seule.
Répondre 200 OK avec {"erreur":"introuvable"} trompe les clients, les caches et les outils de surveillance : le code doit dire la vérité (ici 404).
POST n'est pas idempotent : deux clics, deux commandes. On désactive le bouton après le premier clic, et le serveur refuse une commande déjà reçue grâce à un identifiant unique.
CORS est appliqué par le navigateur. Un attaquant qui envoie ses requêtes avec curl n'en tient pas compte : l'API doit vérifier l'authentification et les droits.
Dans /fiche#quiz, le serveur ne reçoit jamais #quiz : le fragment reste dans le navigateur.
Entraîne-toi
Cherche d'abord, puis ouvre le corrigé.
api.example.com.Voir le corrigéGET /fiches/42 HTTP/1.1 Host: api.example.com Accept: application/json
La ligne de requête (méthode, cible, version), l'en-tête Host obligatoire, Accept pour demander du JSON, puis la ligne vide. Pas de corps pour un GET.
Content-Length pour le corps {"ville":"Genève"} ?Voir le corrigé19. Le corps compte 18 caractères, mais è prend 2 octets en UTF-8, et Content-Length compte des octets.
GET /notes, PUT /notes/3, POST /paiements, DELETE /notes/3 ?Voir le corrigéGET, PUT et DELETE, qui sont idempotentes : les renvoyer donne le même état qu'un seul envoi. Pas le POST : le paiement pourrait être enregistré deux fois.
GET /livres · GET /livres/12 · POST /livres (réponse 201 avec Location: /livres/13) · PATCH /livres/12 avec {"titre":"…"} · DELETE /livres/12 (204) · GET /livres/12/emprunts. Des noms au pluriel, aucun verbe dans les adresses.
Retiens l'essentiel
À retenir
HTTP : un client envoie une requête, un serveur renvoie une réponse. Chaque requête se comprend seule (sans état). Un message : ligne de départ, en-têtes, ligne vide, corps facultatif.
GET lit, POST crée, PUT remplace, PATCH modifie une partie, DELETE supprime.
GET, HEAD, OPTIONS sont sûres ; PUT et DELETE sont idempotentes ; POST et PATCH ni l'un ni l'autre.
2xx réussite, 3xx redirection, 4xx erreur du client, 5xx erreur du serveur ; 401 authentification, 403 droits.
REST : des ressources nommées au pluriel, des méthodes standard, des représentations JSON, sans état. URL : schéma, hôte, port, chemin, requête ; le fragment reste dans le navigateur.
Le navigateur ne laisse un script lire une réponse d'une autre origine que si le serveur l'autorise ; question OPTIONS pour les requêtes non simples.
Douze questions pour finir
Fiche relue et sourcée en septembre 2026, refaite en récit en octobre 2026.