Méthodes et codes de statut

Choisir le bon verbe HTTP et le bon code de réponse : idempotence, familles 2xx à 5xx, en-têtes et négociation de contenu.

L'URL dit sur quoi on agit, la méthode HTTP dit ce qu'on fait, et le code de statut dit ce qui s'est passé. Ces trois éléments forment le contrat de votre API.

📨 Les verbes HTTP

Méthode	Rôle	Corps de requête	Idempotente
`GET`	lire une ressource	non	oui
`POST`	créer une ressource	oui	non
`PUT`	remplacer entièrement une ressource	oui	oui
`PATCH`	modifier partiellement une ressource	oui	non garantie
`DELETE`	supprimer une ressource	non	oui

GET    /articles/42        # lire
POST   /articles           # créer (l'id est attribué par le serveur)
PUT    /articles/42        # remplacer tout l'article 42
PATCH  /articles/42        # ne changer que le titre, par exemple
DELETE /articles/42        # supprimer

🔁 Idempotence

Une opération est idempotente quand la répéter donne le même état final que l'exécuter une seule fois.

DELETE /articles/42 deux fois : l'article reste supprimé, l'état final est identique.
POST /articles deux fois : deux articles créés, l'état final diffère.

Conséquence pratique : un client peut réessayer sans risque un GET, un PUT ou un DELETE après un timeout, mais rejouer un POST peut créer un doublon. Pour sécuriser un POST, utilisez une clé d'idempotence fournie par le client.

🔢 Les familles de codes

200 OK : lecture ou mise à jour réussie, corps renvoyé ;
201 Created : ressource créée, en-tête Location vers la nouvelle URL ;
204 No Content : succès sans corps (typique d'un DELETE).

Retenez la distinction 401 / 403 : 401 signifie « je ne sais pas qui vous êtes », 403 signifie « je sais qui vous êtes, et vous n'avez pas le droit ».

🧾 Répondre correctement côté Express

// Création
app.post("/articles", (req, res) => {
  const article = creerArticle(req.body)
  res.status(201).location(`/articles/${article.id}`).json(article)
})

// Suppression
app.delete("/articles/:id", (req, res) => {
  supprimerArticle(req.params.id)
  res.status(204).end()
})

📦 En-têtes et négociation de contenu

Les en-têtes transportent les métadonnées de l'échange.

Content-Type: application/json : format du corps envoyé ;
Accept: application/json : format souhaité par le client ;
Authorization: Bearer <token> : preuve d'identité ;
Cache-Control et ETag : gestion du cache.

La négociation de contenu permet au serveur de servir plusieurs représentations d'une même ressource selon l'en-tête Accept (JSON, CSV, XML).

Si le client demande un format que le serveur ne sait pas produire, la bonne réponse est 406 Not Acceptable, et non un JSON par défaut.

➡️ Suite

Les bonnes pratiques montrent comment versionner l'API et uniformiser le format des erreurs.

API REST

Terminez le quiz du chapitre pour le marquer comme complété.

Tableau de bord