Qu'est-ce qu'une API REST ? Guide clair
Réponse courte
Une API sert de pont entre programmes pour échanger des données. Une API REST applique les règles REST aux échanges HTTP, généralement autour de ressources et de JSON. Toute API REST appartient à la famille des API, sans que toute API soit REST.
L’essentiel
- Une API définit comment un logiciel demande et reçoit des données.
- Une API REST utilise HTTP et des ressources identifiables.
- Les méthodes GET, POST, PUT et DELETE servent à lire ou modifier des données.
- Le caractère sans état simplifie la mise à l'échelle.
- REST et JSON sont devenus le standard courant des intégrations.
Qu'est-ce qu'une API REST exactement ?
La question « qu'est-ce qu'une API REST ? » appelle une réponse simple : c'est une API qui suit les principes REST pour manipuler des ressources sur HTTP. Au sens large, une API définit comment des programmes envoient des requêtes et reçoivent des réponses. La variante REST ajoute des contraintes sur les URL, les verbes HTTP et l'absence d'état.
Une API reste, en général, un contrat entre applications. Une API REST n'applique qu'une partie de ces règles. Une API RESTful applique toutes les contraintes REST : absence d'état, usage cohérent des verbes HTTP et adresses fondées sur les ressources.
Comment fonctionne une API REST ?
Le client envoie une requête HTTP à une adresse qui identifie une ressource. Le serveur traite la demande, puis renvoie une réponse, souvent en JSON. Chaque ressource a sa propre adresse, par exemple /clients/42 pour un client précis.
Les ressources et les adresses
Une ressource est une donnée ou un objet métier : utilisateur, commande, article. L'adresse URL sert à l'identifier, pas à décrire l'action. On évite donc des adresses comme /obtenirUtilisateur et on préfère /utilisateurs/42.
Les opérations courantes se lisent souvent ainsi : GET /utilisateurs pour la liste, POST /utilisateurs pour créer, GET /utilisateurs/42 pour lire un élément, PUT /utilisateurs/42 pour le remplacer, DELETE /utilisateurs/42 pour le supprimer.
Les méthodes HTTP
| Méthode | Usage courant |
|---|---|
| GET | Lire une ressource ou une liste |
| POST | Créer une ressource |
| PUT | Remplacer une ressource existante |
| DELETE | Supprimer une ressource |
Ces méthodes ne suffisent pas à elles seules : le code de statut HTTP indique le résultat. 200 signifie réussite, 201 création, 404 ressource absente, 500 erreur serveur. Une bonne API utilise ces codes de façon cohérente plutôt que de renvoyer 200 pour toutes les situations.
L'absence d'état
Une API REST stateless ne conserve pas l'état de la session côté serveur entre deux requêtes. Chaque requête contient les informations nécessaires, comme un jeton d'authentification. Cette contrainte facilite la répartition de charge et la mise à l'échelle, car n'importe quel serveur peut traiter la demande.
Les autres contraintes REST courantes sont la séparation client-serveur, la possibilité de mettre en cache certaines réponses, une interface uniforme et une architecture en couches. Elles visent à rendre les échanges prévisibles et à limiter le couplage entre client et serveur.
API, REST API et API RESTful : quelles différences ?
| Terme | Ce qu'il implique |
|---|---|
| API | Contrat général entre logiciels |
| REST API | Suit une partie des principes REST |
| API RESTful | Respecte toutes les contraintes REST |
Pour un petit projet ou un prototype, une API REST souple suffit souvent ; elle laisse plus de liberté dans la conception des points d'entrée et des données. Pour une grande application avec de nombreux services liés, une API RESTful impose des conventions plus stables et facilite la maintenance.
La cohérence compte aussi : quand il faut garantir l'intégrité des transactions et une structure claire, le respect strict des principes REST limite les surprises. Pour des volumes élevés, l'absence d'état et la mise en cache aident à tenir la charge.
Pourquoi REST et JSON dominent les intégrations ?
REST repose sur HTTP, déjà omniprésent. JSON est léger et facile à lire pour un humain comme pour un programme. À eux deux, ils forment un standard simple à déployer sur de nombreuses plateformes.
- Les navigateurs, serveurs et outils en ligne de commande savent déjà parler HTTP.
- Le format JSON se mappe facilement vers des objets dans la plupart des langages.
- La documentation peut décrire des ressources et des méthodes sans imposer un format lourd.
Les agents IA profitent de cette simplicité : ils appellent les mêmes points d'entrée qu'un client humain, reçoivent du JSON prévisible et peuvent lire des données ou déclencher une action. Les interfaces conversationnelles et les workflows automatisés reposent souvent sur des API REST bien conçues.
REST, SOAP et GraphQL
SOAP a précédé REST et utilisait XML, avec des messages plus lourds. REST avec JSON a simplifié les échanges et s'est imposé comme standard du web. GraphQL est puissant, mais sa mise en place est plus complexe ; REST reste dominant globalement.
Le choix dépend du besoin. REST convient bien aux opérations de création, lecture, mise à jour et suppression sur des ressources claires. GraphQL peut aider quand le client doit choisir précisément les champs à recevoir. SOAP reste présent dans certains systèmes d'entreprise anciens.
Exemple de requête et de réponse
Voici une forme typique, sans dépendre d'un service réel :
Requête : GET /commandes/128 avec l'en-tête Accept: application/json.
Réponse : 200 OK, avec un corps JSON contenant l'identifiant, le client et le montant.
Si la commande n'existe pas, la réponse attendue est plutôt 404. Si la requête est mal formée, le serveur peut renvoyer 400. Ces conventions rendent l'API plus facile à utiliser et à déboguer.
Quand choisir REST plutôt qu'une autre approche ?
REST convient aux projets simples dont les échanges de données restent modestes. Il laisse de la souplesse dans la conception des points d'entrée. Pour une grande plateforme avec de nombreux services liés, une approche RESTful stricte aide à garder des conventions stables.
Un backend complet fournit une base de données, des API, l'authentification et des fonctions. Un service de base de données gérée fournit seulement la base de données ; il faut encore construire l'API. REST est souvent la couche qui expose ces données aux clients et aux applications.
Bonnes pratiques de conception
Nommer les ressources au pluriel et garder des adresses stables. Utiliser les codes de statut HTTP pour exprimer le résultat. Versionner l'API quand un changement casse la compatibilité, par exemple avec un préfixe /v1/. Paginer les listes et filtrer les résultats plutôt que de tout renvoyer.
Pour la sécurité, utiliser HTTPS, authentifier chaque requête, valider les entrées et limiter le débit. Pour la performance, mettre en cache les réponses qui changent peu et compresser les transferts. Documenter les champs obligatoires, les erreurs possibles et les formats de date.
Erreurs fréquentes
Utiliser POST pour tout, même la lecture. Mettre l'action dans l'URL au lieu de la méthode HTTP. Renvoyer 200 OK pour une erreur. Oublier la pagination sur une liste. Stocker l'état de session côté serveur alors que l'API se veut sans état. Ces erreurs rendent l'API moins prévisible pour les clients.
Ressources pour approfondir
Pour relier ces notions à la programmation générale, on peut lire Qu'est-ce qu'un langage de programmation ? et Qu'est-ce qu'un algorithme ? Définition et usages. Le choix entre typage statique et dynamique influence aussi la façon dont on modélise les données échangées par une API; voir Typage statique vs dynamique : repères.
Autres questions fréquentes
Une API REST est-elle la même chose qu'une API ?
Non. Toute API REST est une API, mais une API peut utiliser d'autres protocoles ou styles.
Quelles méthodes HTTP utilise-t-on le plus souvent ?
GET, POST, PUT et DELETE servent à lire, créer, remplacer et supprimer des ressources.
Pourquoi utilise-t-on JSON avec REST ?
JSON est léger et facile à lire; il s'échange bien sur HTTP.
Qu'est-ce qu'une API RESTful ?
C'est une API qui respecte toutes les contraintes REST, pas seulement une partie.
REST convient-il aux grands systèmes ?
Oui, surtout sous forme RESTful, car l'absence d'état et les conventions stables aident à monter en charge.
Pages liées
- Rendu côté client vs côté serveur : différences clés
Le rendu côté client génère le HTML dans le navigateur avec JavaScript, tandis que le rendu côté serveur l'envoie déjà complet. Le premier favorise l'interactivité, le second l'affichage initial et le référencement. Le bon choix dépend du contenu, du trafic et des contraintes serveur.
- CORS c'est quoi : rôle, fonctionnement et sécurité
Le partage de ressources entre origines multiples (CORS) est un mécanisme de sécurité exécuté par les navigateurs web pour autoriser ou bloquer les requêtes réseau adressées à un domaine distinct. Il s'appuie sur des en-têtes HTTP dédiés afin de permettre à un serveur d'indiquer explicitement quelles origines ont le droit d'accéder à ses données.
- Cookies web : fonctionnement et gestion des données
Les cookies web constituent des fichiers de données émis par un serveur web et stockés par le navigateur pour préserver l'état d'une connexion. Ils permettent de reconnaître un utilisateur d'une page à l'autre et de mémoriser ses préférences de navigation, compensant ainsi la nature sans état du protocole HTTP.
- Cache webcam : comprendre le cache web
Le cache web est une copie locale de ressources déjà téléchargées. Il accélère l'affichage des pages et réduit les transferts réseau. Le vider corrige surtout des fichiers obsolètes ou corrompus, pas les mots de passe.
- WebSocket what is it : guide pratique
WebSocket est un protocole qui garde une connexion persistante et bidirectionnelle entre client et serveur. Il convient aux applications temps réel qui échangent souvent des données. Il ne remplace pas HTTP pour les pages et les API classiques.
- GraphQL : langage de requête pour API
GraphQL est un langage de requête pour API et un runtime qui exécute les requêtes selon un schéma typé. Le client choisit les champs à recevoir, ce qui évite de récupérer des données inutiles. Les requêtes, mutations et abonnements couvrent la lecture, la modification et, lorsqu'ils sont implémentés, le temps réel.
Comment cette page a été préparée
Avant la rédaction, le sujet a été étudié dans les sources ci-dessous. La page a ensuite passé des contrôles de qualité automatiques.