API REST

Ou : Comment un doctorant a standardisé la manière dont Internet se parle à lui-même

Le serveur de restaurant le plus célèbre du monde

Imaginez un restaurant. Vous (le client) ne pouvez pas entrer dans la cuisine. Vous ne savez pas comment le chef organise ses ingrédients, quelles casseroles il utilise, ni s’il cuisine pieds nus. Vous n’avez pas besoin de le savoir. Vous avez un serveur qui prend votre commande, la transmet à la cuisine, et revient avec votre plat.

Une API REST, c’est ce serveur.

Plus précisément, c’est le contrat entre vous et la cuisine : un menu (les endpoints), des verbes pour commander (GET, POST, PUT, DELETE), et un format de réponse prévisible (généralement du JSON). Tant que tout le monde respecte le contrat, la cuisine peut être réécrite en Go, en Python ou en COBOL¹ — vous ne verrez pas la différence.

REST : l’acronyme qui cache une thèse de doctorat

REST signifie Representational State Transfer. Le terme vient de la thèse de doctorat de Roy Fielding, soutenue en 2000 à l’université de Californie à Irvine. Fielding n’était pas un universitaire déconnecté : il était co-auteur de la spécification HTTP/1.1 et co-fondateur du projet Apache. Quand il a décrit REST, il ne proposait pas un nouveau protocole — il nommait ce qui faisait déjà fonctionner le web.

L’idée fondamentale : le web est un système d’information distribué, et il marche parce qu’il suit un ensemble de contraintes architecturales. Ces contraintes ne sont pas des règles arbitraires. Ce sont les raisons pour lesquelles le web scale à des milliards d’utilisateurs sans qu’un comité central décide qui a le droit de parler à qui.

Vingt-six ans plus tard, REST est devenu le standard de facto pour les API web. Pas parce que c’est parfait — on y reviendra — mais parce que c’est suffisamment bon pour une quantité impressionnante de cas d’usage.

Les six contraintes de REST (dont une que personne n’utilise)

Fielding a défini six contraintes architecturales. Si votre API les respecte toutes, elle est « RESTful ». En pratique, presque personne ne les respecte toutes. Mais les comprendre, c’est comprendre pourquoi REST fonctionne.

1. Séparation client-serveur

Le client (votre application mobile, votre navigateur, votre script Python) et le serveur (le backend qui gère les données) sont indépendants. Le client ne sait pas comment le serveur stocke ses données. Le serveur ne sait pas si le client est un iPhone ou un grille-pain connecté. Chacun peut évoluer sans casser l’autre.

C’est le principe du restaurant : le client commande, la cuisine cuisine. Personne n’a besoin de connaître les détails de l’autre.

2. Sans état (stateless)

Chaque requête contient toutes les informations nécessaires à son traitement. Le serveur ne se souvient pas de vous entre deux requêtes. Pas de « ah oui, c’est le client de tout à l’heure, il voulait du poulet ». Chaque requête est autonome.

C’est contre-intuitif, et c’est précisément ce qui permet à REST de scaler. Si le serveur ne garde pas d’état, vous pouvez mettre 50 serveurs derrière un load balancer et n’importe lequel peut répondre à n’importe quelle requête. Pas de sessions collantes, pas de synchronisation d’état entre serveurs, pas de migraines.

3. Mise en cache

Les réponses doivent indiquer si elles sont cacheables ou non. Si une ressource ne change pas souvent (la liste des pays du monde, par exemple), pourquoi la redemander à chaque fois ? Le cache réduit la charge serveur, la latence réseau, et la facture cloud.

4. Interface uniforme

C’est la contrainte la plus importante et la plus souvent mal comprise. L’interface entre client et serveur doit être uniforme : mêmes conventions pour identifier les ressources (URLs), les manipuler (méthodes HTTP), et décrire les réponses (types MIME, codes de statut).

En pratique, ça veut dire que si vous savez utiliser une API REST, vous savez à peu près utiliser n’importe quelle API REST. GET /users/42 retourne l’utilisateur 42. DELETE /users/42 le supprime. Pas besoin de lire 400 pages de documentation pour deviner que DELETE supprime quelque chose.

5. Système en couches

Un client ne sait pas s’il parle directement au serveur, ou à un intermédiaire (proxy, CDN, gateway). Le système peut avoir autant de couches qu’il veut — cache, sécurité, load balancing — et le client n’en sait rien. Chaque couche ne connaît que ses voisines immédiates.

6. Code à la demande (optionnel)

Le serveur peut envoyer du code exécutable au client (du JavaScript, typiquement). C’est la seule contrainte optionnelle, et dans le contexte des API REST modernes, presque personne ne l’utilise. On la mentionne par complétude académique et par respect pour la thèse de Fielding².

Le vocabulaire de REST : quatre verbes et quelques chiffres

Les méthodes HTTP

REST utilise les méthodes HTTP comme un vocabulaire standardisé. Quatre verbes couvrent 95 % des cas :

On ajoute parfois PATCH (modification partielle) et HEAD (comme GET, mais sans le corps de la réponse — utile pour vérifier si une ressource existe sans la télécharger).

Le mot « idempotent » signifie que faire la même requête deux fois produit le même résultat. DELETE /articles/7 deux fois ? L’article est supprimé la première fois, et la deuxième fois le serveur vous dit qu’il n’existe plus. Le résultat final est le même. POST /articles deux fois ? Vous avez créé deux articles. C’est la différence.

Les codes de réponse HTTP

Le serveur répond avec un code de statut qui résume ce qui s’est passé :

La beauté du système, c’est sa prévisibilité. Un développeur qui reçoit un 404 sait exactement ce qui s’est passé, qu’il travaille avec l’API de Stripe, de Twitter, ou d’une startup dans un garage à Liège.

REST vs SOAP vs GraphQL : le match

REST n’est pas le seul style d’API. Il a des concurrents — certains plus anciens, d’autres plus récents. Voici un comparatif honnête :

SOAP (Simple Object Access Protocol, un nom qui est un mensonge sur chaque mot³) était le standard avant REST. Plus verbeux, plus rigide, mais avec des garanties de sécurité et de transaction que REST n’offre pas nativement. Il survit dans les systèmes bancaires et les grandes entreprises où « on a toujours fait comme ça » est un argument recevable.

GraphQL, créé par Facebook en 2012 et open-sourcé en 2015, résout un vrai problème de REST : l’over-fetching. Avec REST, si vous voulez le nom d’un utilisateur, vous récupérez tout l’objet utilisateur — nom, email, adresse, historique d’achats, tout. Avec GraphQL, vous demandez exactement ce dont vous avez besoin. C’est élégant, mais ça sacrifie la simplicité du cache HTTP et ajoute une couche de complexité côté serveur.

Et puis il y a gRPC, le petit dernier de Google, basé sur Protocol Buffers et HTTP/2. Plus rapide que REST pour la communication entre microservices, mais moins accessible pour les développeurs humains qui aiment pouvoir lire leurs requêtes.

Pourquoi REST a gagné (et où il montre ses limites)

REST domine parce qu’il s’appuie sur ce qui existe déjà : HTTP, URLs, les méthodes standardisées. Pas besoin d’un SDK spécial, pas besoin d’un outil propriétaire. Un curl dans un terminal suffit pour parler à n’importe quelle API REST du monde.

Ajoutez à ça la scalabilité (grâce au stateless), l’interopérabilité (tout langage qui parle HTTP parle REST), et une courbe d’apprentissage douce, et vous comprenez pourquoi Facebook, Google, Stripe, Spotify et à peu près toute entreprise tech expose ses services via REST.

Mais REST n’est pas parfait. Ses limites les plus connues :

• Over-fetching : vous demandez une donnée, vous recevez un roman. C’est le problème que GraphQL résout.
• Under-fetching : vous avez besoin de données réparties sur 5 endpoints différents, donc 5 requêtes HTTP aller-retour. Bonjour la latence sur mobile.
• Pas de standard pour la pagination, le filtrage, le tri : chaque API invente sa propre syntaxe. ?page=2&limit=10 ? ?offset=10 ? ?cursor=abc123 ? Bonne chance pour deviner.
• Versioning : /api/v1/users ou en-tête Accept-Version: 1 ? Le débat dure depuis 15 ans et personne n’a gagné.

Ces limites sont réelles, mais pour 80 % des cas d’usage — des opérations CRUD sur des ressources identifiables — REST reste le choix le plus pragmatique.

Concevoir une API REST qui ne fait pas pleurer les développeurs

Quelques bonnes pratiques, apprises à la dure par des générations de devs backend :

Nommez vos ressources, pas vos actions. /users et non /getUsers. Les méthodes HTTP portent déjà l’action. GET /users pour lire, POST /users pour créer. Pas besoin de le dire deux fois.

Utilisez les bons codes de statut. Un 200 OK avec un body {"error": "Not found"} est un crime contre l’humanité. Utilisez 404.

Sécurisez dès le premier jour. OAuth 2.0 pour l’authentification, HTTPS partout, des tokens JWT pour les sessions stateless. Ne lancez jamais une API en HTTP sans TLS, même « juste pour tester ».

Documentez avec OpenAPI/Swagger. Une API sans documentation est une API que personne n’utilisera (ou que tout le monde utilisera mal, ce qui est pire).

Versionez. Parce qu’un jour vous allez vouloir changer la structure d’une réponse, et vos 200 clients existants ne vont pas apprécier.

FAQ

Est-ce que REST est un protocole ? Non. REST est un style architectural — un ensemble de contraintes. HTTP est le protocole. REST s’appuie sur HTTP mais n’en est pas un.

Quelle est la différence entre REST et RESTful ? REST est le style architectural. « RESTful » décrit une API qui respecte les contraintes REST. En pratique, les deux termes sont utilisés de manière interchangeable, et la plupart des API dites « RESTful » ne respectent pas toutes les contraintes. Et tout le monde s’en accommode.

Est-ce que REST va disparaître au profit de GraphQL ? Probablement pas. GraphQL résout des problèmes spécifiques (over-fetching, applications mobiles complexes), mais ajoute de la complexité. REST reste plus simple pour les cas courants. Les deux coexistent, comme les tournevis plats et cruciformes — différents outils pour différents vis.

Quels outils utiliser pour tester une API REST ? Postman est le plus populaire. curl en ligne de commande pour les puristes. Insomnia pour ceux qui trouvent Postman trop lourd. Et Swagger UI pour explorer une API documentée en OpenAPI.