6 min de lecture

REST API design - 01 - Les principes REST que personne ne lit

Les contraintes REST de Fielding, le modèle de maturite de Richardson, et pourquoi REST n'est pas du CRUD sur HTTP.

REST API architecture principes
REST API design 2 / 25
  1. 01 REST API design - 00 - Pourquoi le design de ton API change tout
  2. 02 REST API design - 01 - Les principes REST que personne ne lit
  3. 03 REST API design - 02 - Des URLs qui ont du sens
  4. 04 REST API design - 03 - Les méthodes HTTP, pour de vrai
  5. 05 REST API design - 04 - Les codes de statut HTTP qu'il faut connaître
  6. 06 REST API design - 05 - Body, headers et le diable dans les détails
  7. 07 REST API design - 06 - La pagination, ou comment ne pas tuer ta base
  8. 08 REST API design - 07 - Filtrage et tri sans prise de tête
  9. 09 REST API design - 08 - La validation avec Zod, gardien de ton API
  10. 10 REST API design - 09 - Erreurs : un format que tes clients vont adorer
  11. 11 REST API design - 10 - Authentification : JWT, API keys et OAuth2
  12. 12 REST API design - 11 - Versioning : quand et comment faire évoluer ton API
  13. 13 REST API design - 12 - CORS : comprendre et debugger les erreurs cross-origin
  14. 14 REST API design - 13 - Rate limiting : protéger ton API sans frustrer tes clients
  15. 15 REST API design - 14 - Caching : les bonnes réponses sont celles qu'on n'envoie pas
  16. 16 REST API design - 15 - Upload de fichiers : multipart, signed URLs et streaming
  17. 17 REST API design - 16 - Relations entre ressources : embarquer, lier ou les deux
  18. 18 REST API design - 17 - HATEOAS : des liens dans tes réponses
  19. 19 REST API design - 18 - OpenAPI : le contrat entre ton API et le monde
  20. 20 REST API design - 19 - Documentation : une API non documentee est une API inutile
  21. 21 REST API design - 20 - Testing : tester ton API sans devenir fou
  22. 22 REST API design - 21 - Webhooks : quand c'est ton API qui appelle
  23. 23 REST API design - 22 - Performance : quand chaque milliseconde compte
  24. 24 REST API design - 23 - Sécurité : les attaques que tu vas subir (et comment t'en protéger)
  25. 25 REST API design - 24 - Glossaire : tous les termes REST API en un seul endroit
← Precedent Suivant →

01 - Les principes REST que personne ne lit

Ce que tu vas apprendre

  • Les 6 contraintes REST définies par Roy Fielding
  • Ce que REST est vraiment (et ce qu'il n'est pas)
  • Le modèle de maturite de Richardson pour évaluer une API

Prerequisites

"Mon API est RESTful"

J'ai perdu le compte du nombre de fois ou j'ai entendu cette phrase en entretien ou en code review. Et dans 90% des cas, l'API en question etait un ensemble d'endpoints POST qui renvoyaient du JSON. C'est du HTTP. C'est du JSON. Mais ce n'est pas REST.

REST -- Representational State Transfer -- est un style architectural decrit par Roy Fielding dans sa these de doctorat en 2000. Fielding n'a pas invente un protocole. Il a observe comment le web fonctionnait et en a extrait des principes. Comprendre ces principes, c'est comprendre pourquoi certaines API "marchent bien" et d'autres non.

Les 6 contraintes REST

1. Client-serveur

Le client et le serveur sont separes. Le client ne sait pas comment les donnees sont stockees. Le serveur ne sait pas comment elles sont affichees. Cette séparation permet a chacun d'évoluer indépendamment.

Ca parait évident en 2026, mais a l'epoque ou Fielding a écrit sa these, beaucoup de systèmes melangeaient les responsabilités.

2. Stateless (sans état)

Chaque requête contient toute l'information nécessaire pour etre traitee. Le serveur ne stocke pas de contexte entre les requêtes. Pas de "session serveur" qui retient ou tu en es.

typescript// Stateless : le token est dans chaque requete
const response = await fetch("/api/orders", {
  headers: {
    Authorization: "Bearer eyJhbGciOiJIUzI1NiIs...",
  },
});

// Stateful (pas REST) : le serveur se souvient de ta session
// Le client envoie juste un cookie de session
// et le serveur cherche qui tu es dans sa memoire

Ca ne veut pas dire que ton API n'a pas de base de donnees. Ca veut dire que le serveur ne garde pas d'état de conversation avec le client. Chaque requête est independante.

3. Cacheable

Les réponses doivent indiquer si elles sont cacheables ou non. Un GET /api/products/42 qui renvoie les memes donnees a chaque appel devrait pouvoir etre cache. Un GET /api/users/me/notifications probablement pas.

httpHTTP/1.1 200 OK
Cache-Control: public, max-age=3600
ETag: "abc123"

{"id": 42, "name": "Widget Pro", "price": 29.99}

On reviendra en détail sur le caching dans un article dédié. Pour l'instant, retiens que c'est une contrainte REST, pas un bonus.

4. Interface uniforme

C'est la contrainte la plus importante et la moins respectee. Elle se décomposé en 4 sous-contraintes :

  • Identification des ressources : chaque ressource a une URI unique (/api/users/42)
  • Manipulation via les representations : tu manipules les ressources à travers leurs representations (JSON, XML, etc.), pas directement
  • Messages auto-descriptifs : chaque message contient assez d'info pour etre compris (Content-Type, méthode HTTP, etc.)
  • HATEOAS : Hypermedia As The Engine Of Application State -- les réponses contiennent des liens vers les actions possibles

HATEOAS est la partie que presque personne n'implemente. On en parlera dans un article dédié. Mais les trois premiers points, tu peux et tu dois les respecter des maintenant.

5. Système en couches

Le client ne sait pas s'il parle directement au serveur ou a un intermediaire (load balancer, CDN, API gateway). Chaque couche ne voit que la couche suivante.

6. Code a la demande (optionnel)

Le serveur peut envoyer du code executable au client (JavaScript par exemple). C'est la seule contrainte optionnelle. En pratique, pour les API REST, on l'ignore la plupart du temps.

Ce que REST n'est PAS

REST n'est pas :

  • CRUD sur HTTP : REST utilise les méthodes HTTP, mais une ressource n'est pas forcement une table en base
  • JSON sur HTTP : REST ne prescrit pas de format. JSON est une convention moderne
  • Un standard : REST est un style architectural, pas une spec. Il n'y a pas de RFC "REST"
  • L'oppose de GraphQL : GraphQL et REST resolvent des problèmes différents, parfois les memes

L'erreur la plus courante que je vois, c'est de penser en tables de base de donnees. "J'ai une table users, donc j'ai un endpoint /users." Parfois oui. Mais une ressource REST peut etre un concept abstrait : /api/search, /api/reports/monthly-revenue, /api/auth/login. On verra ca en détail dans l'article sur les URLs.

Le modèle de maturite de Richardson

Leonard Richardson a propose un modèle a 4 niveaux pour évaluer la "RESTfulness" d'une API :

Niveau 0 -- Le marais du POX

Un seul endpoint, une seule méthode (souvent POST), tout passe dans le body.

httpPOST /api
Content-Type: application/json

{"action": "getUser", "userId": 42}

C'est du RPC deguise en HTTP. L'API de livraisons dont je parlais dans l'introduction etait la.

Niveau 1 -- Ressources

Chaque ressource a son URI, mais on n'utilise pas les méthodes HTTP correctement.

httpPOST /api/users/42
POST /api/users/42/delete
POST /api/users/42/update

Niveau 2 -- Verbes HTTP

On utilise les bonnes méthodes HTTP et les bons codes de statut. C'est la que se situent la majorite des "bonnes" API aujourd'hui.

httpGET /api/users/42          -> 200 OK
POST /api/users            -> 201 Created
PUT /api/users/42          -> 200 OK
DELETE /api/users/42       -> 204 No Content
GET /api/users/999         -> 404 Not Found

Niveau 3 -- HATEOAS

Les réponses contiennent des liens hypermedia vers les actions disponibles.

json{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "_links": {
    "self": { "href": "/api/users/42" },
    "orders": { "href": "/api/users/42/orders" },
    "update": { "href": "/api/users/42", "method": "PUT" },
    "delete": { "href": "/api/users/42", "method": "DELETE" }
  }
}

Mon avis : vise le niveau 2 minimum. Le niveau 3 est elegant mais rarement nécessaire pour les API internes. Pour les API publiques, ca peut valoir le coup.

En pratique

La plupart des API que tu vas construire n'ont pas besoin d'etre "100% REST" selon la these de Fielding. Ce qui compte, c'est de comprendre les principes pour prendre de bonnes décisions. Stateless, interface uniforme, bons codes de statut -- ca, c'est non negociable.

Le reste de cette serie va te montrer comment appliquer ces principes concrètement, endpoint par endpoint, header par header. On commence avec le design des URLs.

Tu peux retrouver le plan complet de la serie sur paltemps.fr.

Résumé

  • REST est un style architectural avec 6 contraintes, pas juste "du JSON sur HTTP"
  • Stateless et interface uniforme sont les deux contraintes les plus impactantes
  • Le modèle de Richardson donne 4 niveaux de maturite : vise au minimum le niveau 2
  • Une ressource REST n'est pas forcement une table en base de donnees

Precedent : Introduction | Suivant : Design des URLs

Sources

Publie le · Mis a jour le

Articles liés

Réservez un audit gratuit de 30 minutes. Je vous montre concrètement ce qu'on peut automatiser.

Découvrir Pal'Temps