On m'a posé la question trois fois la même semaine, dans trois contextes différents. Un développeur junior qui débute sur un projet d'intégration. Un chef de produit qui voulait comprendre pourquoi son équipe perdait deux jours sur un connecteur. Et un client qui me demandait si son « API REST » pouvait aussi être une « API tout court ». À chaque fois, la même confusion revenait : on parle d'API REST comme d'un objet unique, alors qu'il s'agit d'un contrat tacite entre deux programmes, avec des règles précises que peu de gens prennent le temps d'énumérer.
Ce qui m'a frappé, en préparant cet article, c'est qu'aucune des ressources que j'ai consultées ne détaille vraiment les six contraintes posées par Roy Fielding en 2000 dans sa thèse. On répète « architecture REST », on cite Fielding comme on cite un ancêtre, et on passe directement aux exemples de requêtes. Sauf que ces six contraintes, c'est précisément ce qui distingue une API REST d'une API HTTP quelconque. Comprendre le fonctionnement des API REST sans elles, c'est comme apprendre à conduire sans savoir ce qu'est un embrayage.
Points clés à retenir
- REST est un style architectural, pas un protocole ni une norme : il décrit six contraintes que l'API doit respecter.
- Une API REST s'appuie sur les méthodes HTTP (GET, POST, PUT, PATCH, DELETE) et manipule des ressources identifiées par des URL.
- L'absence d'état côté serveur (stateless) est la contrainte la plus structurante : chaque requête contient tout ce qu'il faut pour être comprise.
- Les codes de statut HTTP (200, 201, 404, 500…) font partie du contrat : ils disent au client ce qui s'est passé.
- REST n'est ni meilleur ni pire que SOAP ou GraphQL : ce sont des compromis différents selon les besoins.
- L'authentification, la version et la pagination sont des questions à trancher tôt, sinon elles deviennent des dettes techniques.
Qu'est-ce qui fait vraiment qu'une API est REST ?
Une API REST, c'est une interface qui respecte le style architectural REST — pour Representational State Transfer. Le mot « acronyme » qu'on lit parfois est impropre : REST est un sigle, formé des initiales de trois mots anglais. Et RESTful est l'adjectif qu'on colle à une API qui s'y conforme.
La confusion la plus fréquente ? Croire qu'une API qui répond en JSON sur du HTTP est forcément REST. Faux. Vous pouvez avoir une API HTTP qui échange du JSON et qui n'est pas REST du tout — par exemple, si elle stocke la session côté serveur entre deux appels. Le format (JSON, XML, HTML) et le transport (HTTP, HTTPS) ne sont pas des critères. Ce qui compte, ce sont les contraintes. Les voici, et je les ai rangées dans l'ordre où je les explique à mes stagiaires.
Les six contraintes de Fielding, en clair
- Client-serveur : le client et le serveur évoluent séparément, tant que l'interface entre eux ne change pas.
- Sans état (stateless) : le serveur ne garde aucune mémoire de la requête précédente. Chaque appel est autonome.
- Cacheable : les réponses doivent pouvoir être marquées comme mises en cache ou non, pour économiser du trafic.
- Interface uniforme : c'est le point le plus important et le plus mal compris — des ressources identifiées par des URL, des représentations manipulées via des méthodes HTTP standard, des messages auto-descriptifs, et l'hypermédia comme moteur de l'application.
- Système en couches : un client peut ignorer qu'il parle à un proxy, un équilibreur de charge, ou un serveur de cache.
- Code à la demande (facultatif) : le serveur peut envoyer du code exécutable au client. En pratique, presque personne ne l'utilise.
La contrainte « sans état », je l'ai mal comprise pendant presque un an. Je pensais que ça voulait dire « pas de base de données ». Non. Ça veut dire que le serveur ne se souvient pas de vous entre deux requêtes. Si vous êtes connecté, c'est parce que chaque requête contient un jeton d'authentification. Si vous paginez un résultat, chaque page doit contenir tout ce qu'il faut pour charger la suivante. C'est plus verbeux, mais c'est ce qui rend une API facile à scaler horizontalement — un serveur peut tomber, un autre prend la relève, aucune session n'est perdue.
Comment se passe un appel concret ? Méthode, URL, réponse
Une API REST s'articule autour de ressources, et chaque ressource porte une URL propre. Le verbe HTTP dit ce qu'on veut faire dessus. C'est tout le modèle.
Prenons l'exemple d'une petite boutique en ligne. Une URL comme /commandes/1042 désigne une ressource : la commande 1042. Ce qui change selon l'appel, c'est la méthode.
| Méthode | Ce qu'elle fait | Exemple d'URL | Code de retour typique |
|---|---|---|---|
| GET | Lit une ressource sans la modifier | /commandes/1042 | 200 si trouvée, 404 sinon |
| POST | Crée une nouvelle ressource | /commandes | 201 avec l'URL de la ressource créée |
| PUT | Remplace intégralement une ressource | /commandes/1042 | 200 ou 204 |
| PATCH | Modifie partiellement une ressource | /commandes/1042 | 200 ou 204 |
| DELETE | Supprime une ressource | /commandes/1042 | 204 (sans contenu) |
Un détail que j'ai vu causer de vraies disputes en équipe : la différence entre PUT et PATCH. PUT remplace tout l'objet. Si vous envoyez un PUT avec seulement deux champs sur un objet qui en compte cinq, les trois autres sont écrasés. PATCH, lui, ne touche qu'aux champs présents dans le corps de la requête. Confondre les deux a failli me coûter une base de production, une fois — un collègue avait fait un PUT partiel en pensant faire un PATCH. Depuis, on a une règle : PATCH sauf raison explicite de tout réécrire.
Les codes de statut sont une partie du contrat
Un code de statut n'est pas un détail cosmétique. C'est la première chose que le client lit pour savoir s'il doit réessayer, afficher une erreur, ou enregistrer le résultat.
- 2xx : ça s'est bien passé (200 OK, 201 Created, 204 No Content).
- 3xx : la ressource a bougé ailleurs (301, 302).
- 4xx : la faute vient du client (400 mauvaise requête, 401 non authentifié, 403 interdit, 404 introuvable, 429 trop de requêtes).
- 5xx : la faute vient du serveur (500 erreur interne, 503 indisponible).
J'ai vu des API renvoyer systématiquement 200 avec un champ erreur: true à l'intérieur. C'est une hérésie pour les outils intermédiaires — les proxies, les systèmes de monitoring, les bibliothèques clientes — qui ne comprennent pas ce que l'API raconte sans lire tout le corps de la réponse. Bon, soyons honnêtes : c'est parfois fait exprès pour contourner des pare-feux mal configurés. Mais c'est rarement un bon choix à long terme.
Différence entre API et API REST : ce qu'on confond
Toute API REST est une API. L'inverse n'est pas vrai. Une API est une interface — une porte d'entrée programmatique vers un service. REST, c'est une manière de concevoir cette porte.
Une bibliothèque logicielle expose une API. Une base de données expose une API. Un fichier de configuration en ligne de commande expose une API. Aucune n'est forcément REST. Vous pouvez tout à fait avoir une API qui fonctionne par appels de fonctions à distance (RPC), où l'URL ressemble à /getCommandeParId?id=1042, avec un verbe dans le chemin. Ça marche. Ce n'est pas REST, parce que la ressource n'est pas identifiée par un nom mais par une action, et parce que ça contredit l'idée d'interface uniforme.
API REST ou SOAP : comment trancher
SOAP est un protocole, pas un style. Il impose un format de message basé sur XML, un contrat formel (WSDL), et un ensemble de règles strictes pour la structure des échanges. REST ne vous impose presque rien sur le format, tant que les contraintes sont respectées.
En pratique, REST a gagné la majorité des usages web parce qu'il est plus léger à implémenter. Mais SOAP garde des partisans dans des contextes où la rigueur du contrat, la sécurité intégrée (WS-Security) ou la gestion de transactions distribuées comptent plus que la légèreté. Dans la banque, l'assurance, la santé, on rencontre encore beaucoup de SOAP, et le remplacer coûte cher.
Pour vous décider, posez-vous trois questions : avez-vous besoin d'un contrat formel opposable ? Travaillez-vous avec des partenaires qui ne jureront que par WS-* ? Ou avez-vous surtout besoin d'aller vite, avec des outils qui existent déjà partout ? Dans les cas web classiques, la réponse est presque toujours REST.
Ce qu'on ne dit presque jamais
Les ressources que j'ai consultées en préparant cet article oublient trois sujets, et c'est presque toujours les trois qui font mal en production.
L'authentification n'est pas un détail
REST ne dit rien sur l'authentification. C'est à vous de choisir. En 2026, on voit surtout deux familles : les jetons OAuth 2 (avec parfois OpenID Connect par-dessus) pour les accès à des comptes tiers, et les clés d'API pour des échanges serveur à serveur simples. Les sessions par cookie existent aussi, mais elles contredisent l'idée de stateless si on n'y prend pas garde.
Le point que j'ai mis du temps à comprendre : un jeton d'authentification fait partie du contrat sans état. Il doit voyager à chaque requête, dans l'en-tête Authorization, et le serveur doit pouvoir le valider seul, sans consulter un état gardé en mémoire. Sinon, vous cassez la contrainte.
Versionner une API, c'est choisir sa politique
Il y a deux grandes écoles : mettre la version dans l'URL (/v1/commandes, /v2/commandes) ou la mettre dans un en-tête. J'ai testé les deux sur des projets, et franchement, la version dans l'URL gagne pour la lisibilité — on voit dans un log quelle version le client utilise. L'inconvénient, c'est qu'elle fige la structure de l'URL. La version en en-tête est plus élégante théoriquement, mais en pratique elle se perd dans les caches, les proxies et la doc.
Quoi qu'il en soit, ne sortez pas une API publique sans politique de version. La première rupture que vous ferez cassera des clients si vous n'avez pas préparé le terrain.
La pagination et les limites de débit
Un GET qui renvoie 200 000 résultats n'est pas une API, c'est un déni de service en devenir. La pagination par curseur (un jeton qui indique la position) est aujourd'hui préférée à la pagination par numéro de page, parce qu'elle résiste aux insertions concurrentes. Et un système de limite de débit (rate limiting) qui renvoie 429 quand on dépasse est une politesse que vos clients apprécieront — mieux vaut une limite claire qu'un serveur qui tombe.
Spoiler : ces trois sujets sont rarement dans les tutoriels d'introduction, et pourtant ils font la différence entre une API qui tient trois mois et une qui tient cinq ans.
En résumé, un contrat plus qu'un format
Comprendre le fonctionnement des API REST, ce n'est pas mémoriser une liste de méthodes HTTP. C'est comprendre qu'on accepte un ensemble de règles — l'absence d'état, l'interface uniforme, les ressources nommées — pour gagner quelque chose en échange : la possibilité d'évoluer, de cacher, de répartir la charge, de faire tomber un serveur sans perdre une session. Le prix, c'est une certaine verbosité : chaque requête doit tout dire.
La prochaine fois que vous tomberez sur une « API REST » qui renvoie du JSON sur du HTTP, posez-vous la vraie question. Est-ce que je peux appeler deux fois la même URL, dans deux ordres différents, et obtenir le même résultat ? Si oui, le style tient. Si non, il y a quelque chose qui échappe aux contraintes — et c'est peut-être très bien ainsi, tant que vous savez pourquoi.
