Méthodes et codes de statut

Objectifs

À la fin de cette leçon, vous saurez :

• choisir la méthode HTTP adaptée à chaque intention, en comprenant l'idempotence ;
• relier méthodes et opérations CRUD d'une application ;
• classer les codes de statut par familles et citer les essentiels ;
• distinguer 401/403 et 400/404 — les nuances qui font les API propres.

🔗 Pour vous rafraîchir la mémoire : anatomie d'une requête HTTP

Les méthodes : l'intention déclarée du client

La méthode est le premier mot de la requête : elle déclare l'INTENTION avant toute donnée. C'est un contrat sémantique entre client et serveur :

Méthode	Intention	Corps requis	Idempotent	Sûr
GET	lire	non	oui	oui
POST	créer / soumettre	oui	non	non
PUT	remplacer intégralement	oui	oui	non
PATCH	modifier partiellement	oui	en principe	non
DELETE	supprimer	rarement	oui	non

Deux propriétés colonnes méritent leur définition exacte :

• Idempotent : répéter la requête produit le même état final que l'exécuter une fois. Supprimer deux fois la tâche 7 → toujours « pas de tâche 7 » (idempotent). Créer deux fois un utilisateur avec POST → DEUX utilisateurs (non idempotent) ;
• Sûr : la requête ne modifie rien côté serveur — seule GET l'est. C'est pourquoi les moteurs de recherche préchargent les liens GET sans crainte.

Pourquoi l'idempotence compte-t-elle tant ? À cause des reprises après erreur réseau : votre POST part, la connexion tombe avant la réponse — le client sait-il qu'il peut réessayer ? Pour un DELETE ou un PUT : oui, sans risque. Pour un POST : danger de doublon ! Toute API sérieuse documente ce comportement ; toute application mobile vit avec.

Le mappage CRUD : la grammaire des API

CRUD (Create, Read, Update, Delete) se traduit naturellement en méthodes + chemins :

GET    /tasks        → liste toutes les tâches          (Read)
POST   /tasks        → crée une tâche                   (Create)
GET    /tasks/7      → lit la tâche 7                   (Read)
PATCH  /tasks/7      → modifie une partie de la 7       (Update)
DELETE /tasks/7      → supprime la 7                    (Delete)

Observez la régularité : le chemin désigne LA RESSOURCE (pluriel pour les collections, identifiant pour l'individu), la méthode porte L'ACTION. Aucun /createTask, aucun /deleteTask?id=7 — ces formes mélangent action dans l'URL et trahissent souvent des API improvisées. Cette convention REST structure toutes les API modernes, y compris celle de NestJS que vous construirez en partie 6.

Les codes de statut : le verdict structuré

La première ligne de réponse porte un code à trois chiffres. La centaine donne la famille — apprenez les familles avant les codes :

1xx informationnel   (rare au quotidien)
2xx SUCCÈS           ← tout s'est bien passé
3xx REDIRECTION      ← allez voir ailleurs
4xx FAUTE DU CLIENT  ← la requête était mauvaise
5xx PANNE DU SERVEUR ← le serveur a échoué

Cette lecture par famille oriente instantanément le débogage : un 4xx se corrige CÔTÉ CLIENT (mauvaise URL, mauvais format), un 5xx se corrige côté SERVEUR (lire ses logs). Souvenez-vous du chapitre débogage : identifier la famille avant de chercher la cause.

Codes essentiels à connaître par cœur :

Code	Signification	Usage typique
200 OK	succès standard	lecture réussie
201 Created	ressource créée	réponse à un POST réussi (+ en-tête Location: vers la nouvelle ressource)
204 No Content	succès sans corps	réponse à un DELETE
301/302	redéfini/temporairement ailleurs	migrations, HTTPS forcé
400 Bad Request	requête mal formée/invalide	validation refusée (JSON cassé, champ manquant)
401 Unauthorized	qui êtes-vous ?	absence ou invalidité d'authentification
403 Forbidden	je sais qui vous êtes, mais non	rôle insuffisant
404 Not Found	ressource absente	mauvais identifiant
409 Conflict	conflit d'état	doublon unique, version obsolète
500 Internal Server Error	bug côté serveur	exception non gérée

Trois nuances à graver :

• 401 vs 403 : 401 = inconnu (« présentez vos papiers »), 403 = connu mais interdit (« vos papiers sont bons, mais cet endroit ne vous concerne pas »). On ne peut pas juger une autorisation sans identité : toujours 401 d'abord ;
• 400 vs 404 : 400 = la requête est syntaxiquement/sémantiquement invalide, 404 = la requête est valide mais la cible n'existe pas (vous avez vécu cette distinction avec nc au chapitre 9) ;
• 500 = faute du serveur, jamais du client. Si VOTRE code renvoie des 500, c'est lui qu'il faut déboguer — chapitre logs et tests en partie 7.

Exercice

Pour chaque scénario : méthode, chemin et code de réponse attendu.

1. Afficher la liste des utilisateurs.
2. Créer l'utilisateur Paul.
3. Demander l'utilisateur n°999 (qui n'existe pas).
4. Modifier seulement l'email de Paul (id 42).
5. Supprimer la tâche n°12.
6. Un visiteur non connecté demande ses favoris.
7. Deux requêtes identiques POST /users {"name":"Paul"} partent à cause d'une erreur réseau : combien d'utilisateurs Paul existent ensuite ?
8. Question de synthèse : votre API renvoie 500 sur GET /users. Où cherchez-vous le problème ?

Résumé

• Méthode = intention déclarée ; idempotence = même effet final si répétée (clé des reprises réseau).
• CRUD ↔ GET/POST/PATCH/DELETE sur des chemins-ressources.
• Familles : 2xx succès, 3xx ailleurs, 4xx faute client, 5xx panne serveur.
• 201 pour créer (+ Location), 204 pour supprimer, 401 ≠ 403, 400 ≠ 404.