HTTP — Méthodes, Codes et Headers

Référence développeur/API pour les méthodes HTTP, les codes de statut et les headers les plus courants. Ces éléments sont le vocabulaire de toute API REST, GraphQL ou WebSocket.

Pour la structure bas niveau des requêtes HTTP, TLS et les versions du protocole → Requêtes HTTP et HTTPS

---

Méthodes HTTP

Méthode	Sémantique	Idempotent	Safe	Body requête	Body réponse
GET	Lire une ressource	✅	✅	Non	Oui
POST	Créer / soumettre	❌	❌	Oui	Oui
PUT	Remplacer entièrement	✅	❌	Oui	Oui
PATCH	Modifier partiellement	✅*	❌	Oui	Oui
DELETE	Supprimer	✅	❌	Non	Rarement
HEAD	Comme GET, sans le body de réponse	✅	✅	Non	Non
OPTIONS	Méthodes autorisées sur cette URL (CORS preflight)	✅	✅	Non	Oui

Idempotent : appeler N fois donne le même résultat qu’une seule fois.
Safe : ne modifie pas l’état du serveur (lecture seule).

Quand utiliser PATCH vs PUT ?

Ressource : { "id": 42, "name": "Alice", "role": "admin", "email": "alice@ex.com" }

PUT /users/42  ← remplace TOUT l'objet
Body : { "name": "Alice", "role": "viewer", "email": "alice@ex.com" }
       ↑ doit inclure tous les champs, même ceux non modifiés

PATCH /users/42  ← modifie uniquement ce qui est envoyé
Body : { "role": "viewer" }
       ↑ seul le champ modifié est nécessaire

---

Codes de statut HTTP

2xx — Succès

Code	Signification	Quand l’utiliser
200 OK	Requête réussie	GET, PUT, PATCH — réponse avec body
201 Created	Ressource créée	POST réussi — inclure Location: /users/42
202 Accepted	Accepté mais traitement asynchrone	Tâches longues (background jobs)
204 No Content	Succès sans body	DELETE, PUT sans retour
206 Partial Content	Contenu partiel	Téléchargement avec Range

3xx — Redirection

Code	Signification	Quand l’utiliser
301 Moved Permanently	URL définitivement déplacée	Migration de domaine
302 Found	Redirection temporaire	Redirection après POST (PRG pattern)
304 Not Modified	Contenu inchangé	Cache côté client toujours valide
307 Temporary Redirect	Redirection temporaire (méthode conservée)	Préférer à 302 pour les APIs
308 Permanent Redirect	Redirection permanente (méthode conservée)	Préférer à 301 pour les APIs

4xx — Erreur client

Code	Signification	Quand l’utiliser
400 Bad Request	Requête malformée	JSON invalide, paramètre manquant
401 Unauthorized	Non authentifié	Token absent, expiré ou invalide
403 Forbidden	Non autorisé	Authentifié mais pas les droits
404 Not Found	Ressource introuvable	ID inexistant
405 Method Not Allowed	Méthode non autorisée	DELETE sur une ressource en lecture seule
409 Conflict	Conflit d’état	Email déjà utilisé, version obsolète
410 Gone	Ressource définitivement supprimée	Ressource qui existait mais plus disponible
422 Unprocessable Entity	Données sémantiquement incorrectes	Validation métier échouée
429 Too Many Requests	Rate limiting	Quota dépassé — inclure Retry-After

5xx — Erreur serveur

Code	Signification	Quand l’utiliser
500 Internal Server Error	Erreur interne non gérée	Exception non catchée
502 Bad Gateway	Le proxy/LB n’a pas eu de réponse valide	Backend en panne
503 Service Unavailable	Service temporairement indisponible	Maintenance, surcharge
504 Gateway Timeout	Timeout de réponse	Backend trop lent

401 vs 403 — la confusion fréquente

401 Unauthorized (mal nommé — devrait être "Unauthenticated") :
  → Le serveur ne sait pas qui tu es
  → Tu dois t'authentifier (token manquant, expiré, invalide)
  → Réponse : "Connecte-toi d'abord"

403 Forbidden :
  → Le serveur sait qui tu es, mais tu n'as pas la permission
  → Tu es authentifié mais pas autorisé
  → Réponse : "Tu n'as pas les droits pour ça"

---

Headers HTTP importants

Headers de requête (Client → Serveur)

Header	Exemple	Rôle
Host	api.exemple.com	Domaine ciblé — obligatoire en HTTP/1.1
Authorization	Bearer eyJhbGci...	Token d’authentification
Content-Type	application/json	Format du body envoyé
Accept	application/json	Format de réponse souhaité
Accept-Language	fr-FR, fr;q=0.9	Langue préférée
Accept-Encoding	gzip, deflate, br	Compression acceptée
Cookie	session=abc123	Cookies envoyés au serveur
User-Agent	Mozilla/5.0	Identifiant du client
X-Forwarded-For	192.168.1.5	IP originale (ajoutée par le proxy)
X-Request-ID	f47ac10b-58cc	ID unique de la requête (tracing)
Origin	https://app.exemple.com	Origine de la requête (CORS)
Referer	https://exemple.com/page	URL de la page précédente
If-None-Match	"abc123"	ETag pour cache conditionnel
If-Modified-Since	Sat, 01 Jan 2026 00:00:00 GMT	Date pour cache conditionnel

Headers de réponse (Serveur → Client)

Header	Exemple	Rôle
Content-Type	application/json; charset=utf-8	Format du body de réponse
Content-Length	1234	Taille du body en octets
Content-Encoding	gzip	Compression appliquée
Cache-Control	max-age=3600, public	Règles de mise en cache
ETag	"abc123"	Version de la ressource (cache)
Last-Modified	Sat, 01 Jan 2026 00:00:00 GMT	Date de dernière modification
Location	/api/users/42	URL de redirection (201, 301, 302)
Set-Cookie	session=xyz; HttpOnly; Secure; SameSite=Strict	Définit un cookie
WWW-Authenticate	Bearer realm="api"	Méthode d’auth requise (401)
Retry-After	60	Secondes avant de réessayer (429, 503)
X-RateLimit-Limit	1000	Quota total
X-RateLimit-Remaining	743	Requêtes restantes
X-Request-ID	f47ac10b-58cc	ID de la requête pour le tracing

Headers de sécurité

Header	Exemple	Rôle
Strict-Transport-Security	max-age=31536000; includeSubDomains	Force HTTPS (HSTS)
Content-Security-Policy	default-src 'self'	Empêche XSS et injection
X-Content-Type-Options	nosniff	Empêche le MIME sniffing
X-Frame-Options	DENY	Empêche le clickjacking (iframe)
Access-Control-Allow-Origin	https://app.exemple.com	CORS — domaines autorisés
Access-Control-Allow-Methods	GET, POST, PUT, DELETE	CORS — méthodes autorisées
Permissions-Policy	geolocation=()	Contrôle les APIs navigateur

---

CORS — Cross-Origin Resource Sharing

Le navigateur bloque par défaut les requêtes vers un domaine différent de la page courante.

Page : https://app.exemple.com
API  : https://api.exemple.com   ← domaine différent → bloqué par défaut

Preflight (requête OPTIONS automatique du navigateur) :
  OPTIONS /api/users HTTP/1.1
  Origin: https://app.exemple.com
  Access-Control-Request-Method: POST
  Access-Control-Request-Headers: Content-Type, Authorization

Réponse du serveur si CORS configuré :
  HTTP/1.1 204 No Content
  Access-Control-Allow-Origin: https://app.exemple.com
  Access-Control-Allow-Methods: GET, POST, PUT, DELETE
  Access-Control-Allow-Headers: Content-Type, Authorization
  Access-Control-Max-Age: 86400   ← cache le preflight 24h

# FastAPI — configuration CORS
from fastapi.middleware.cors import CORSMiddleware
 
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.exemple.com"],  # jamais "*" en prod si credentials
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["Authorization", "Content-Type"],
    allow_credentials=True,
)

---

Format des erreurs d’API

Une réponse d’erreur doit être cohérente et informative pour le client.

// Format recommandé (RFC 7807 — Problem Details)
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
 
{
  "type": "https://api.exemple.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Le champ 'email' est invalide",
  "instance": "/api/users",
  "errors": [
    { "field": "email", "message": "Format invalide" },
    { "field": "role",  "message": "Valeur inconnue : 'superadmin'" }
  ]
}

// À éviter — retourner 200 avec une erreur dans le body
HTTP/1.1 200 OK
{ "success": false, "error": "something went wrong" }   ← antipattern

---

En relation avec

• API — Vue d’ensemble — types d’APIs
• API REST — utilisation des méthodes et codes dans une API REST
• Authentification API — header Authorization, tokens, OAuth2
• Requêtes HTTP et HTTPS — structure bas niveau du protocole HTTP, TLS, versions