← API REST : concevoir, mûrir, documenter

Niveau 1 : introduire les ressources

≈ 15 minutes · Prérequis : Le modèle de Richardson — Niveau 0 : le tunnel POX/RPC

Le gain du jour : franchir la première marche du modèle de Richardson en découpant l’URI unique du niveau 0 en une multitude d’URI, une par ressource.

Le changement : une URI par ressource

Au niveau 1, on arrête d’envoyer toutes les requêtes vers une seule URI (/api). On introduit des ressources, chacune avec sa propre URI — exactement la notion vue en leçon 1.

Niveau 0 (un seul point d’entrée, l’action est dans le corps) :

POST /api
{"action": "getUser", "userId": 42}

POST /api
{"action": "getUserOrders", "userId": 42}

POST /api
{"action": "deleteUser", "userId": 42}

Niveau 1 (une URI par ressource) :

POST /users/42/get
POST /users/42/orders/get
POST /users/42/delete

C’est un vrai progrès : un opérateur qui lit les logs du serveur voit immédiatement quelle ressource est concernée par chaque requête, juste en lisant l’URI — plus besoin d’ouvrir le corps de chaque requête. On peut router différemment selon la ressource, appliquer des règles de sécurité par URI, etc.

Ce qui manque encore : le verbe reste figé

Remarque bien : le verbe HTTP reste POST dans tous les cas, y compris pour une simple lecture (/users/42/get). L’action elle-même (get, delete) est encore encodée dans l’URI, ce qui est presque aussi étrange que de l’encoder dans le corps — on a juste déplacé le problème.

Le piège du niveau 1 : des URI qui ressemblent à des appels de fonction

/users/42/get et /users/42/delete ressemblent à des URI REST (elles varient !), mais elles cachent encore des verbes déguisés en noms de chemin. Une vraie URI REST identifie une chose (/users/42), jamais une action sur cette chose. Le symptôme classique du niveau 1 : des URI qui se terminent par un verbe à l’infinitif (/get, /create, /cancel, /activate).

C’est exactement la limite que corrige le niveau 2 : au lieu d’écrire l’action dans l’URI, on la confie au verbe HTTP — GET /users/42 au lieu de POST /users/42/get, DELETE /users/42 au lieu de POST /users/42/delete. C’est le sujet de la prochaine leçon.

Pourquoi s’arrêter ici serait dommage

Une API de niveau 1 a déjà une structure de ressources claire — c’est un vrai changement de mentalité par rapport au niveau 0. Mais elle laisse sur la table les bénéfices que HTTP offre gratuitement dès qu’on utilise les bons verbes : cache automatique sur les GET, sûreté et idempotence garanties, codes de statut porteurs de sens. Beaucoup d’API dites « REST » en pratique ne dépassent jamais ce niveau 1 — Fowler l’appelle d’ailleurs « a resource API that ignores HTTP verbs ».

Vérifie ta compréhension

1. Qu'est-ce qui change entre le niveau 0 et le niveau 1 du modèle de Richardson ?

2. Quel est le symptôme typique d'une API restée bloquée au niveau 1 ?

À toi de jouer

Réécris ces trois appels de niveau 0 en URI de niveau 1 (une ressource par URI, verbe HTTP toujours POST) : {"action": "listOrders", "userId": 42}, {"action": "cancelOrder", "orderId": 7}, {"action": "createOrder", "userId": 42}.
Repère, dans une API que tu as déjà utilisée (documentation en ligne d’un service public par exemple), une URI qui se termine par un verbe. Note-la : on la corrigera avec les vrais verbes HTTP dans la prochaine leçon.

Pour aller plus loin

📖 Source principale : Martin Fowler, « Richardson Maturity Model », section « Level 1: Resources ».