REST mature : ressources, versions, erreurs

Prérequis (cursus dev) : requêtes et réponses, NestJS ; cours Réseaux 7.1.

Pourquoi

« API REST » recouvre tout, du propre au chaotique. Une API mature se consomme sans deviner ni lire le code source — et évolue sans casser ses clients.

Concepts

• Ressources + verbes : GET /orders/123, POST /orders, PATCH /orders/123/status. Le verbe porte l'action, l'URL nomme la chose. GET /getOrder?id=1 = RPC déguisé.
• Statuts honnêtes (cf. Réseaux 7.1) : 201 + Location à la création, 404 vs 403 (ne pas révéler l'existence), 409 conflit, 422 entité incompréhensible, 429 quota. Jamais d'erreur en 200.
• Versionnement : /v1/ dans l'URL (simple, explicite) ou négociation (Accept). Règle : on ajoute, on ne casse pas ; on déprécie (Sunset header + changelog) avant de retirer.
• Pagination + filtres : ?page&limit (plafonné !), curseur pour les gros volumes (?after=id), tri explicite. Sans plafond, un GET /orders vide la base un jour de charge.

Exemple : créer proprement

POST /v1/orders → 201 Created
Location: /v1/orders/456
{ "id": "456", "status": "pending", ... }

Cas réel

GET /users sans pagination sur 800k lignes : timeout, mémoire explosée, base à genoux — découvert en prod un lundi. Plafond + curseur ajoutés : 40 ms par page, incident clos.

Pièges

• 403 vs 404 : 403 sur ressource inexistante révèle son existence (énumération). 404 dans le doute.
• Casser un champ « inutilisé » : quelqu'un l'utilise toujours. Déprécier, mesurer, puis retirer.
• N+1 côté client (une requête par ligne affichée) : endpoints d'agrégat (?include=) ou pagination adaptée.

À retenir

Verbes + ressources, statuts honnêtes, version qui n'endommage pas, pagination plafonnée.