REST API

Une REST API (ou API REST, pour Representational State Transfer) est une API qui fait communiquer deux applications en s’appuyant sur les règles du protocole HTTP, celui que votre navigateur utilise déjà pour charger une page web. Le style a été formalisé par Roy Fielding dans sa thèse de doctorat en 2000 et il est devenu la manière par défaut de construire une API sur le web. Quand un fournisseur vous annonce « on a une API », il s’agit presque toujours d’une REST API.

Le principe tient en une phrase : utiliser HTTP tel qu’il a été conçu. Les URL désignent des ressources (un client, une facture, une commande), les verbes HTTP disent ce qu’on veut en faire et les codes de réponse indiquent comment cela s’est passé. Comme ces conventions sont partagées par tout le web, un développeur qui n’a jamais vu votre API sait déjà, à peu de choses près, comment lui parler. Cette familiarité, plus qu’une supériorité technique, explique la domination de REST dans l’écosystème SaaS.

Comment fonctionne une REST API

Des ressources identifiées par des URL

Dans une REST API, chaque objet manipulé par le système est une ressource avec une adresse propre, appelée endpoint. /customers désigne l’ensemble des clients, /customers/123 le client numéro 123, /customers/123/invoices ses factures. La hiérarchie se lit comme un plan de classement, et on devine l’adresse d’une ressource qu’on n’a jamais consultée. Une ressource n’est pas forcément une table en base de données : elle correspond à un concept métier, et c’est au backend de faire la traduction.

Les verbes HTTP

L’action à réaliser est portée par le verbe HTTP de la requête, et non par l’URL. Cinq verbes couvrent l’essentiel et recoupent les quatre opérations CRUD (create, read, update, delete) que connaît toute base de données :

• GET lit une ressource sans rien modifier : la liste des clients, le détail d’un produit.
• POST crée une ressource : une inscription, une nouvelle commande.
• PUT remplace intégralement une ressource existante.
• PATCH modifie une partie de la ressource, par exemple le seul statut d’une commande.
• DELETE la supprime.

Une propriété de ces verbes compte beaucoup en production : GET, PUT et DELETE sont idempotents, c’est-à-dire qu’envoyer la même requête deux fois produit le même résultat qu’une seule. POST ne l’est pas. Si une connexion mobile coupe pendant un paiement et que l’application réessaie, un POST naïf peut débiter le client deux fois. Les API de paiement comme Stripe résolvent ce problème avec une clé d’idempotence, un identifiant unique joint à la requête qui permet au serveur de reconnaître un doublon.

Les codes de réponse HTTP

Chaque réponse commence par un code à trois chiffres. Les 2xx signalent un succès : 200 pour une lecture, 201 pour une création, 204 pour une suppression sans contenu. Les 4xx désignent une erreur du côté du client : 400 pour une requête malformée, 401 pour une authentification absente, 403 pour un accès interdit, 404 pour une ressource inexistante, 422 pour des données refusées à la validation, 429 quand le client dépasse le nombre de requêtes autorisées. Les 5xx signalent une panne côté serveur, 500 pour une erreur interne et 503 pour un service indisponible.

Renvoyer le bon code permet à l’application cliente de réagir seule : réessayer plus tard sur un 503, demander à l’utilisateur de se reconnecter sur un 401. Une API qui renvoie 200 avec « erreur » écrit dans le corps de la réponse oblige chaque client à écrire du code spécial pour la comprendre.

Les principes de l’architecture REST

Le serveur ne garde pas d’état entre deux requêtes. Chaque requête transporte tout ce qu’il faut pour la traiter, y compris l’identité de l’appelant, en général sous forme de token. Le serveur n’a pas à « se souvenir » de la requête précédente, ce qui permet de répartir le trafic sur autant de machines qu’on veut. C’est l’une des raisons pour lesquelles une REST API tient bien la montée en charge, et un levier direct de scalabilité.

Les lectures se mettent en cache. HTTP fournit nativement les mécanismes (en-têtes Cache-Control, ETag) pour réutiliser une réponse encore valide au lieu de la redemander. Pour un SaaS à fort trafic, une politique de cache bien réglée réduit la facture d’infrastructure de façon visible.

L’interface est uniforme. Les mêmes verbes, les mêmes conventions d’URL et les mêmes codes de réponse s’appliquent à toutes les ressources. Qui sait manipuler /customers sait manipuler /invoices.

Client et serveur évoluent séparément. Le frontend web, l’application mobile ou l’intégration d’un partenaire ne connaissent que le contrat de l’API. On peut réécrire tout le serveur sans qu’ils s’en aperçoivent, tant que le contrat tient. Cette séparation rend possible une architecture en microservices, où chaque service expose sa propre REST API.

Une précision qui évite des débats stériles : la thèse de Fielding impose une contrainte de plus, où chaque réponse contient les liens vers les actions possibles (le fameux HATEOAS), et son auteur a rappelé en 2008 que la plupart des API dites REST ne la respectent pas. Il a raison, et cela n’a aucune importance pour votre produit. Ce que le marché appelle REST API est une API HTTP qui manipule des ressources en JSON avec les bons verbes et les bons codes, soit le niveau 2 du modèle de maturité de Richardson.

Concevoir une REST API de qualité

Nommer des ressources, pas des actions

Les URL contiennent des noms au pluriel, jamais des verbes. /customers est correct, /getCustomers ou /createCustomer ne le sont pas : l’action est déjà dans le verbe HTTP.

Paginer, filtrer, trier

Une API qui renvoie dix mille lignes d’un coup est lente pour tout le monde. La pagination (?page=2&limit=50, ou un curseur pointant vers le dernier élément lu) découpe les résultats en lots, et les paramètres de filtre et de tri évitent au client de tout télécharger pour n’en garder qu’une partie. La réponse doit inclure le total, la page courante et le lien vers la suivante.

Versionner sans casser les clients

Une API publique est une promesse. Dès qu’un client externe s’y branche, chaque changement incompatible (un champ renommé, un format modifié) casse son intégration. Le versioning permet aux anciens clients de continuer à fonctionner pendant qu’ils migrent. La forme la plus courante est un préfixe d’URL (/v1/customers, /v2/customers). Stripe et GitHub préfèrent identifier chaque version par une date, que le client fixe dans un en-tête et ne change que lorsqu’il est prêt. Dans tous les cas, il faut annoncer la politique, documenter les dépréciations et laisser un délai avant de couper une ancienne version.

Documenter avec OpenAPI

Une API sans documentation est une API que personne n’utilise. La spécification OpenAPI (anciennement Swagger, en version 3.2 depuis 2025) décrit chaque endpoint, ses paramètres et ses réponses dans un fichier lisible par les machines, dont on génère une documentation interactive, des clients dans plusieurs langages et des tests. Beaucoup d’équipes écrivent ce contrat avant le code : selon le State of the API Report 2025 de Postman, 82 % des organisations se disent « API-first ». Cette logique où la spécification devient la source de vérité est au cœur du spec-driven development.

Sécuriser chaque couche

Le chiffrement HTTPS est obligatoire, sans exception. L’authentification passe par des clés d’API pour les intégrations serveur à serveur et par OAuth 2.0 avec des tokens JWT quand un utilisateur agit via une application tierce. L’autorisation vérifie ensuite ce que l’appelant a le droit de faire, avec des périmètres (scopes) restreints au strict nécessaire. Toute donnée entrante est validée avant traitement, avec des bibliothèques comme Zod en TypeScript. Enfin, le rate limiting plafonne le nombre de requêtes par client et renvoie un 429 au-delà, ce qui protège contre les abus comme contre le script mal écrit d’un client de bonne foi.

Structurer les réponses d’erreur

Au-delà du code HTTP, le corps d’une erreur doit dire ce qui s’est passé et comment le corriger. La RFC 9457 (Problem Details for HTTP APIs, publiée en 2023) fournit un format standard : un type d’erreur, un titre, un détail lisible et, si utile, un lien vers la documentation. Une erreur bien écrite coûte quelques minutes à celui qui l’écrit et fait gagner des heures à ceux qui la reçoivent.

Les limites de REST et les alternatives

REST a deux défauts connus. Le premier est la sur-récupération : un GET renvoie tous les champs d’une ressource même si le client n’en veut que deux, ce qui pèse sur une connexion mobile. Le second est la sous-récupération : pour afficher un écran qui combine un client, ses commandes et le détail de chaque commande, il faut enchaîner plusieurs requêtes, chacune ajoutant de la latence. Quand les données sont très liées et que les clients ont des besoins d’affichage variés, GraphQL permet de demander exactement ce qu’on veut en une seule requête.

Pour la communication interne entre microservices, où la performance prime sur la lisibilité, gRPC transporte des messages binaires typés et remplace parfois REST. Et pour prévenir un client qu’un événement vient d’avoir lieu (un paiement reçu, une commande expédiée), le serveur REST ne peut que répondre à des questions : il faut lui ajouter des webhooks. La plupart des produits SaaS exposent une REST API publique complétée par des webhooks, et ne passent à GraphQL ou gRPC que sur un besoin précis.

REST API et agents IA

Depuis 2024, une REST API a un nouveau type de consommateur : les agents IA. Un modèle de langage qui doit créer un devis dans votre outil ou lire l’état d’une commande le fait à travers des outils, et ces outils sont le plus souvent des appels à une REST API existante. Le protocole MCP, qui standardise la connexion entre un modèle et des outils externes, s’appuie très souvent sur un serveur qui traduit ses requêtes vers une API REST. Notre article sur le Model Context Protocol détaille ce mécanisme.

Cela change la façon de juger une API. Un agent ne lit pas un tutoriel : il lit la spécification OpenAPI, les descriptions de chaque paramètre et les messages d’erreur. Une API aux noms explicites et aux erreurs structurées se branche à un agent en quelques heures, là où une API bricolée oblige à écrire une couche d’adaptation à la main.

FAQ REST API

REST API, API REST, RESTful : est-ce la même chose ?

Oui. « REST API » est la forme anglaise, « API REST » la forme française, et « RESTful » un adjectif qui qualifie une API respectant les conventions REST. Les trois désignent la même chose en pratique.

Quel format de données utilise une REST API ?

Le JSON dans la quasi-totalité des cas : il est léger, lisible par un humain et compris nativement par tous les langages. Le XML subsiste dans des systèmes anciens, notamment ceux qui utilisent SOAP, un protocole plus lourd que REST a largement remplacé sur le web.

Faut-il une REST API pour lancer un MVP ?

Si votre produit a une interface web ou mobile et un serveur, vous en avez déjà une : c’est ce qui relie les deux. La question est plutôt de savoir s’il faut l’ouvrir à des tiers. Pour un MVP, non, sauf si des intégrations font partie de la proposition de valeur. Appliquer les conventions REST dès le début coûte peu et rend l’ouverture facile le jour où un client la demande.

Comment Polara Studio construit les REST API

Chez Polara Studio, REST est le choix par défaut pour les API, parce qu’il couvre la grande majorité des besoins de nos clients avec le moins de complexité possible.

Nos API sont écrites en TypeScript strict sur Node.js. Les schémas de validation définis en entrée servent aussi à typer les réponses et à générer la spécification OpenAPI, si bien que la documentation ne peut pas dériver du code. Des tests automatisés vérifient le contrat à chaque modification, ce qui protège les intégrations existantes quand l’API évolue.

Nous appliquons les conventions décrites sur cette page sans exception : des URL orientées ressources, les bons codes HTTP, une pagination systématique, un versioning annoncé et des erreurs structurées. Le résultat est une API qu’un développeur frontend, une équipe mobile, un partenaire ou un agent IA peut utiliser sans formation.