← API REST : concevoir, mûrir, documenter

Les verbes HTTP et les codes de statut

≈ 20 minutes · Prérequis : HTTP, client-serveur, ressources : les fondations

Le gain du jour : connaître par cœur les verbes HTTP qui comptent vraiment, leurs deux propriétés clés (sûreté et idempotence), et savoir choisir le bon code de statut pour chaque réponse.

Les verbes : l’action sur la ressource

HTTP définit une poignée de verbes (méthodes). Une API REST correcte n’en utilise que quelques-uns, chacun avec un sens précis :

Verbe	Sur une collection `/users`	Sur une ressource `/users/42`
GET	Lister les utilisateurs	Lire l’utilisateur 42
POST	Créer un nouvel utilisateur	(rare) action non-standard sur 42
PUT	(rare) remplacer toute la collection	Remplacer entièrement l’utilisateur 42
PATCH	(rare)	Modifier partiellement l’utilisateur 42
DELETE	(rare) vider la collection	Supprimer l’utilisateur 42

Deux propriétés qui changent tout

Chaque verbe a deux propriétés qui déterminent ce que le client — et tout intermédiaire (proxy, cache, load-balancer) — a le droit de supposer.

Sûr (safe) : n’a aucun effet de bord, ne modifie rien côté serveur. Un navigateur peut précharger un lien GET sans risque ; un moteur de recherche peut explorer des millions de pages GET sans rien casser.

Idempotent : répéter la même requête N fois produit le même effet qu’une seule fois. Si la connexion coupe et que le client renvoie la requête par sécurité, un verbe idempotent ne fait courir aucun risque.

Verbe	Sûr ?	Idempotent ?
GET	✅	✅
PUT	❌	✅
DELETE	❌	✅
PATCH	❌	❌ (en général)
POST	❌	❌

Pourquoi PUT est idempotent et POST ne l’est pas

PUT /users/42 {"name": "Alice"} remplace tout l’utilisateur 42 par ces données — le refaire 10 fois laisse l’utilisateur 42 strictement identique. POST /users {"name": "Alice"} crée un nouvel utilisateur à chaque appel — le refaire 10 fois crée 10 utilisateurs Alice différents. C’est la différence entre « remplacer une chose identifiée » et « créer une nouvelle chose ».

Cette table n’est pas une curiosité théorique : les caches HTTP, les navigateurs et les proxys s’appuient dessus pour décider s’ils peuvent rejouer une requête automatiquement en cas d’échec réseau. Violer ces règles (faire un GET qui supprime des données, par exemple) casse cette confiance et peut provoquer des bugs très difficiles à diagnostiquer.

PUT vs PATCH : la nuance qui piège tout le monde

PUT attend la ressource complète : si tu omets un champ, il est souvent effacé (remplacé par sa valeur par défaut).
PATCH n’attend que les champs à modifier : les autres restent intacts.

PUT /users/42
{"name": "Alice", "email": "alice@exemple.com", "age": 30}

PATCH /users/42
{"age": 31}

Avec PATCH, seul age change ; name et email restent ce qu’ils étaient.

Les codes de statut : dire pourquoi, pas seulement si

Un code de statut est un nombre à 3 chiffres dont le premier chiffre donne la catégorie :

Plage	Catégorie	Sens
2xx	Succès	La requête a été traitée comme prévu
3xx	Redirection	La ressource est ailleurs
4xx	Erreur client	Le client a fait une erreur (mauvaise requête, non autorisé…)
5xx	Erreur serveur	Le serveur a planté, ce n’est pas la faute du client

Les codes à connaître par cœur pour concevoir une API :

Code	Nom	Quand l’utiliser
`200 OK`	Succès générique	GET, PUT, PATCH réussis
`201 Created`	Créé	POST qui a créé une ressource (avec un header `Location`)
`204 No Content`	Pas de contenu	Succès sans corps à renvoyer (souvent DELETE)
`400 Bad Request`	Requête invalide	Le corps ou les paramètres sont mal formés
`401 Unauthorized`	Non authentifié	Le client n’a pas prouvé qui il est
`403 Forbidden`	Interdit	Le client est identifié, mais n’a pas le droit
`404 Not Found`	Introuvable	La ressource n’existe pas à cette URI
`409 Conflict`	Conflit	La requête entre en conflit avec l’état actuel (doublon, version obsolète)
`422 Unprocessable Entity`	Entité invalide	Bien formé syntaxiquement, mais invalide sémantiquement
`429 Too Many Requests`	Trop de requêtes	Limite de débit (rate limiting) dépassée
`500 Internal Server Error`	Erreur serveur	Bug ou panne côté serveur

401 vs 403 : la confusion classique

401 = « je ne sais pas qui tu es » (pas de jeton, ou jeton invalide/expiré) → le client devrait se (re)connecter. 403 = « je sais qui tu es, mais tu n’as pas la permission » → se reconnecter ne changera rien, il faudrait des droits différents.

Vérifie ta compréhension

1. Un client envoie deux fois la même requête DELETE /users/42 (la connexion a coupé entre les deux). Quel est l'effet si DELETE est bien implémenté en idempotent ?

2. Quelle différence essentielle entre PUT et PATCH ?

3. Un client envoie un jeton d'authentification expiré. Quel code de statut est le plus approprié ?

À toi de jouer

Pour chaque scénario, choisis le verbe HTTP et le code de statut de la réponse : créer une commande, annuler une commande existante, modifier uniquement l’adresse de livraison d’une commande, récupérer la liste des commandes d’un client.
Ouvre les outils de développement de ton navigateur sur un site que tu utilises, et trouve une requête POST. Regarde le code de statut renvoyé — est-ce 200 ou 201 ? Le serveur suit-il la convention ?

Pour aller plus loin

📖 Source principale : MDN — Méthodes de requête HTTP et MDN — Codes de statut de réponse HTTP, les références les plus à jour et les plus lisibles sur le sujet.

🗂 Fiche de référence associée : Verbes, codes, en-têtes — antisèche.