← API REST : concevoir, mûrir, documenter

Niveau 2 : exploiter les verbes HTTP

≈ 20 minutes · Jalon M3 · Prérequis : Niveau 1 : introduire les ressources

Le gain du jour : atteindre le niveau où se trouve la grande majorité des « bonnes » API REST du monde réel — celui où le verbe HTTP porte enfin l’action, et où les codes de statut portent enfin un sens.

Le changement : le verbe HTTP remplace le verbe dans l’URI

Au niveau 2, on applique ce qu’on a vu en leçons 1 et 2 : le verbe HTTP (GET, POST, PUT, PATCH, DELETE) exprime l’action, l’URI ne nomme plus que la ressource.

Niveau 1 (verbe caché dans l’URI, méthode HTTP toujours POST) :

POST /users/42/get
POST /users/42/delete
POST /users/42/orders/get
POST /users
{"action": "create", "name": "Bob"}

Niveau 2 (le verbe HTTP porte l’action) :

GET    /users/42
DELETE /users/42
GET    /users/42/orders
POST   /users
{"name": "Bob"}

C’est une transformation profonde, pas cosmétique : chaque ligne ci-dessus est maintenant sûre ou idempotente selon des règles standard (leçon 2), donc cachable, rejouable en sécurité, et compréhensible par des outils génériques — navigateurs, proxys, passerelles d’API, générateurs de documentation — sans qu’ils aient besoin de connaître ton application.

Les codes de statut prennent enfin du sens

Niveau 0/1 : le serveur répond souvent 200 OK pour tout, même une erreur métier cachée dans le corps. Niveau 2 : le code de statut est la réponse à « est-ce que ça s’est bien passé, et pourquoi » :

POST /users
{"email": "deja-utilise@exemple.com"}

HTTP/1.1 409 Conflict
{"error": "Un compte existe déjà avec cet email"}

DELETE /users/999

HTTP/1.1 404 Not Found

Un outil de supervision peut désormais compter les 5xx pour détecter une panne serveur, ou les 409 pour détecter un pic de doublons — sans lire un seul octet du corps de la réponse.

Là où se situe la grande majorité des « API REST » en production

Le niveau 2 est, en pratique, le point d’arrivée de la plupart des API qui se disent RESTful — GitHub, Stripe, Twitter à leurs débuts. C’est un excellent équilibre : bénéfices réels de HTTP, sans la complexité additionnelle du niveau 3 (hypermédia), que très peu d’API publiques adoptent réellement.

Un point encore flou : la collection vs l’élément

Au niveau 2, on distingue systématiquement l’URI de la collection de celle de l’élément :

GET  /users        → liste (collection)
POST /users        → créer un élément dans la collection
GET  /users/42     → un élément précis
PUT  /users/42     → remplacer cet élément précis
PATCH /users/42    → modifier partiellement cet élément précis
DELETE /users/42   → supprimer cet élément précis

Cette symétrie (URI de collection au pluriel, URI d’élément = collection + identifiant) est devenue la convention de facto de l’immense majorité des API REST — s’en écarter sans raison forte surprendra tous les développeurs qui consomment ton API.

Vérifie ta compréhension

1. Qu'est-ce qui distingue fondamentalement le niveau 2 du niveau 1 ?

2. Pourquoi les codes de statut deviennent-ils plus utiles au niveau 2 ?

À toi de jouer

Reprends les URI de niveau 1 que tu as écrites dans la leçon précédente et transforme-les en véritables appels de niveau 2 : bon verbe HTTP, URI qui ne contient plus que des noms de ressources.
Pour une API que tu connais bien (une que tu utilises dans un projet, ou celle d’un service public), vérifie : la collection est-elle bien au pluriel ? Le verbe HTTP correspond-il à l’action réelle (GET pour lire, jamais pour modifier) ?

Pour aller plus loin

📖 Source principale : Martin Fowler, « Richardson Maturity Model », section « Level 2: HTTP Verbs ».

🗂 Fiche de référence associée : Verbes, codes, en-têtes — antisèche.