Formations — 1 037 leçons en français

Accueil › Node.js › Ressources, verbes et URL

Ressources, verbes et URL

Concevoir une API RESTdebutant

Une URL d'API nomme une chose. La méthode HTTP dit ce qu'on en fait.

GET    /commandes          lister
POST   /commandes          créer
GET    /commandes/42       lire une
PUT    /commandes/42       remplacer
PATCH  /commandes/42       modifier partiellement
DELETE /commandes/42       supprimer

Six opérations, un seul nom : commandes, au pluriel. Aucun verbe dans le chemin. POST /creerCommande et POST /supprimerCommande répètent dans l'URL ce que la méthode exprime déjà, et personne ne devine le reste de l'API à partir d'un seul exemple.

Ce que les verbes garantissent

Méthode Sûre Idempotente
GET oui oui
PUT non oui
DELETE non oui
POST non non

Sûre : ne modifie rien, donc on peut la rejouer et la mettre en cache. Idempotente : dix envois identiques laissent le même état qu'un seul.

Ces garanties ne sont pas décoratives. Un client mobile qui perd le réseau réessaie. Un équilibreur de charge rejoue une requête interrompue. Avec PUT, c'est sans conséquence. Avec POST, le client est débité deux fois.

// Le client fournit une clé ; le serveur ne traite qu'une fois.
const reponse = await fetch("/paiements", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "idempotency-key": idDeTentative,       // stable entre les réessais
  },
  body: JSON.stringify({ montant: 4990 }),
});

C'est la seule façon correcte de rendre une création réessayable.

Les termes à connaître

Ressource

La chose que l'API expose — une commande, un client, un paiement. L'URL la nomme, au pluriel, et ne décrit jamais l'action qu'on lui applique.

Collection

L'ensemble des ressources d'un type, à /commandes. Un élément de cette collection vit à /commandes/{id} : même nom, un segment de plus.

Méthode sûre

Une méthode qui ne modifie rien côté serveur — GET, HEAD, OPTIONS. Un intermédiaire peut la rejouer, la mettre en cache, la préchauffer.

Idempotence

Rejouer la requête à l'identique laisse le serveur dans le même état qu'un seul envoi. PUT et DELETE le garantissent, POST non.

Clé d'idempotence

Un identifiant fourni par le client dans un en-tête, que le serveur mémorise pour ne traiter qu'une fois un POST réessayé. Indispensable sur un paiement.

PUT

Remplace la ressource entière par le corps envoyé. Un champ omis est un champ effacé — c'est la définition, pas un effet de bord.

PATCH

Applique une modification partielle. Les champs absents du corps restent inchangés, ce qui rend le null explicite ambigu si on n'y pense pas.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.