Cheat sheet — Codes HTTP & conventions REST

Méthodes HTTP

Méthode	Usage	Idempotent	Corps requête
GET	Lire une ressource / collection	Oui	Non
POST	Créer une ressource, action	Non	Oui
PUT	Remplacer une ressource entière	Oui	Oui
PATCH	Modifier partiellement	Non	Oui
DELETE	Supprimer	Oui	Non

Codes d’état les plus utiles

2xx — Succès

Code	Sens	Quand
200 OK	Succès	GET, PUT, PATCH réussis
201 Created	Créé	POST qui crée une ressource (renvoyer l’id / Location)
204 No Content	Succès sans corps	DELETE réussi

4xx — Erreur client

Code	Sens	Quand
400 Bad Request	Requête invalide	validation échouée, JSON malformé
401 Unauthorized	Non authentifié	token absent / session absente
403 Forbidden	Authentifié mais non autorisé	rôle insuffisant, ressource d’autrui
404 Not Found	Ressource inexistante	id inconnu
409 Conflict	Conflit d’état	doublon (e-mail unique déjà pris)
413 Payload Too Large	Corps trop volumineux	limite express.json({ limit })
415 Unsupported Media Type	Mauvais Content-Type	body non-JSON sur une route JSON
422 Unprocessable Entity	Sémantique invalide	validation métier (alternative à 400)
429 Too Many Requests	Quota dépassé	rate limiting (ajouter Retry-After)

5xx — Erreur serveur

Code	Sens	Quand
500 Internal Server Error	Erreur imprévue	exception non gérée (message générique !)
503 Service Unavailable	Indisponible	maintenance, surcharge

Codes non standard. N’inventez pas de codes. Ils ne sont compris ni par les clients, ni par les proxies, ni par la supervision. 499 est d’ailleurs utilisé en interne par nginx (« client closed request »).

401 vs 403

• 401 : « je ne sais pas qui tu es » → authentifie-toi.
• 403 : « je sais qui tu es, mais tu n’as pas le droit ».
• Pour éviter d’exposer l’existence d’une ressource (énumération / BOLA), on renvoie parfois 404 au lieu de 403.

Conventions de nommage des routes

GET    /api/v1/users            # liste
POST   /api/v1/users            # création
GET    /api/v1/users/:id        # détail
PUT    /api/v1/users/:id        # remplacement
PATCH  /api/v1/users/:id        # modification partielle
DELETE /api/v1/users/:id        # suppression
GET    /api/v1/users/:id/orders # sous-ressource

• Noms au pluriel, en minuscules, pas de verbe dans l’URL (le verbe = la méthode HTTP).
• Versionner l’API (/api/v1/...) dès le départ.
• Filtres / pagination en query string : GET /users?role=admin&page=2&limit=20.
• Ordre des routes Express : déclarer les routes fixes (/users/search) avant les routes paramétrées (/users/:id).

Réponse JSON standardisée

// Succès
{ "status": "success", "data": { "id": 1, "name": "Alice" } }
// Erreur
{ "status": "error", "error": "Email invalide" }

Rester cohérent sur toute l’API : mêmes champs, mêmes conventions.

En-têtes utiles

En-tête	Rôle
Content-Type: application/json	format du corps
Authorization: Bearer <token>	JWT / OAuth2
RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset	quotas
Retry-After	délai avant nouvelle tentative (avec 429/503)
Location	URL de la ressource créée (avec 201)

Tester en ligne de commande

curl -i http://localhost:3000/api/v1/users      # en-têtes + code
curl -s -X POST http://localhost:3000/api/v1/users \
  -H "Content-Type: application/json" -d '{"name":"Alice"}'
curl -s --get http://localhost:3000/ping --data-urlencode "host=127.0.0.1"