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.
PUTetDELETEle garantissent,POSTnon.- 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
POSTré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
nullexplicite ambigu si on n'y pense pas.
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.