Une API REST permet à un logiciel client de communiquer avec un serveur au moyen du protocole HTTP. Le client demande une ressource ou une action, puis le serveur renvoie une réponse comprenant notamment un code de statut et, selon le cas, un corps de réponse. Pour débuter, retenez surtout le rôle des URL, le sens des méthodes HTTP, les messages d'erreur et la manière d'envoyer une requête sans exposer d'information sensible.
REST signifie Representational State Transfer. Il s'agit d'un style d'architecture décrit par Roy Fielding dans une thèse consacrée aux architectures logicielles et aux systèmes en réseau. Une API dite REST s'appuie couramment sur HTTP pour organiser les échanges entre un client et un serveur.
Le client peut être une application exécutée dans un navigateur, un programme en ligne de commande, un service côté serveur ou tout autre logiciel capable d'émettre une requête HTTP. Le serveur reçoit cette requête, l'interprète, effectue le traitement prévu et construit une réponse. Cette réponse indique si l'opération a réussi, échoué ou nécessite une autre action.
Dans ce dialogue, HTTP apporte un vocabulaire partagé. La méthode exprime l'intention de la requête, l'URL désigne ce qui est visé, les en-têtes précisent le contexte de l'échange et le code de statut résume le résultat. La sémantique de ces éléments est définie par HTTP Semantics.
Avant d'écrire un appel, il est utile de consolider les bases du langage qui l'exécutera. Le guide pour apprendre JavaScript en 2026, du niveau débutant au niveau avancé peut notamment vous aider à mieux comprendre les promesses, les objets et la gestion des erreurs utilisés avec fetch.
Une API n'est donc pas une base de données à laquelle le navigateur accéderait directement. C'est une interface qui expose des opérations et des représentations choisies par son concepteur. Le client ne doit pas présumer de la structure interne du serveur : il doit suivre le contrat public décrit dans la documentation de l'API.
Une ressource est l'élément que l'API rend accessible : cela peut représenter un article, une collection d'articles, un profil ou un autre objet prévu par le service. Une URL permet de viser cette ressource. Avec l'URL fictive https://api.example.com/articles, le chemin /articles peut désigner une collection d'articles.
La ressource n'est pas nécessairement identique à la façon dont les données sont stockées. Une API peut exposer un article sous la forme d'un document JSON alors que le serveur s'appuie sur une organisation interne différente. Cette séparation est précieuse : elle évite que le client dépende directement des choix d'implémentation du serveur.
Une URL sert avant tout à identifier une cible. La méthode HTTP indique ensuite l'intention : lire, créer, remplacer, modifier partiellement ou supprimer. Évitez de déduire le comportement d'une API à partir du seul nom d'un chemin. Deux API peuvent organiser leurs URL différemment tout en respectant la même sémantique HTTP.
Le choix de la couche de stockage reste un sujet distinct de l'interface HTTP. Pour réfléchir à cette articulation sans confondre ressources API et modèle de données, consultez SQL ou NoSQL pour votre premier projet de développeur en 2026. L'API constitue une frontière utile entre ce que le client manipule et les décisions de persistance prises côté serveur.
Lorsque vous lisez une URL dans une documentation, cherchez ce qu'elle désigne, les méthodes qu'elle accepte et les données attendues. Une documentation claire précise aussi quelles réponses sont possibles pour chaque opération.
Les méthodes HTTP ne sont pas de simples verbes interchangeables. Elles portent une sémantique qui aide le serveur, le client et les personnes qui maintiennent l'API à se comprendre. Employer une méthode adaptée rend le comportement plus prévisible et facilite le traitement des réponses.
| Méthode | Usage habituel | Sûre | Idempotente |
|---|---|---|---|
GET |
Lire une ressource ou une collection | Oui | Oui |
POST |
Créer une ressource ou déclencher un traitement | Non | Non |
PUT |
Remplacer une ressource | Non | Oui |
PATCH |
Modifier partiellement une ressource | Non | À vérifier dans la documentation |
DELETE |
Supprimer une ressource | Non | Oui |
Une méthode est dite sûre lorsqu'elle ne modifie pas l'état du serveur. GET est donc destiné à la lecture. Il peut renvoyer une représentation d'une ressource, mais il ne doit pas servir à demander une création ou une suppression simplement parce que cela semble plus rapide à écrire.
Une méthode est idempotente lorsque répéter la même requête produit le même état final sur le serveur. Cette idée compte particulièrement lorsqu'une réponse est incertaine ou lorsqu'un client doit réessayer une opération. PUT remplace une ressource et DELETE supprime une ressource : leur répétition vise le même état final. À l'inverse, POST n'est pas idempotente : il ne faut pas supposer qu'une répétition aura le même effet qu'un unique envoi.
PATCH, défini par une spécification distincte, sert à appliquer une modification partielle. Son comportement concret doit être lu attentivement dans la documentation de l'API, notamment pour savoir quelle forme de modification est attendue et ce qu'implique une répétition de la requête.
Quelques réflexes vous éviteront de nombreux malentendus :
GET lorsque vous demandez une lecture ;POST si la documentation prévoit une création ou un traitement déclenché par cette méthode ;PUT seulement lorsque le remplacement de la ressource correspond au contrat annoncé ;PATCH pour une modification partielle telle qu'elle est documentée ;DELETE lorsque la suppression est explicitement proposée par l'API.La méthode correcte ne garantit pas à elle seule le succès. Les données envoyées, les droits d'accès et l'état de la ressource peuvent modifier la réponse reçue. C'est pourquoi la lecture des codes de statut est la suite logique de la lecture des méthodes.
Le code de statut est une information essentielle de la réponse HTTP. Les codes sont regroupés par familles : 1xx pour une information, 2xx pour un succès, 3xx pour une redirection, 4xx pour une erreur attribuée à la requête du client et 5xx pour une erreur côté serveur.
| Code | Signification | Réflexe côté client |
|---|---|---|
200 OK |
La requête a réussi | Lire le corps si la documentation en prévoit un |
201 Created |
Une ressource a été créée | Utiliser la représentation renvoyée si elle est fournie |
204 No Content |
La requête a réussi sans corps de réponse | Ne pas tenter de lire du JSON absent |
400 Bad Request |
La requête est invalide | Vérifier les données et le format envoyés |
401 Unauthorized |
L'authentification est absente ou invalide | Vérifier le mécanisme d'authentification prévu |
403 Forbidden |
L'accès est interdit | Ne pas contourner la règle d'accès |
404 Not Found |
La ressource est introuvable | Vérifier l'URL et l'existence de la ressource |
429 Too Many Requests |
Trop de requêtes ont été envoyées | Réduire ou différer les appels selon la documentation |
500 Internal Server Error |
Une erreur interne est survenue côté serveur | Signaler le contexte utile et traiter l'échec côté client |
Un 200 signifie que l'opération a réussi, mais il ne dit pas à lui seul quelle structure contient le corps de réponse. Un 201 est associé à la création d'une ressource. Un 204 indique au contraire un succès sans contenu : appeler un analyseur JSON sur une réponse vide serait alors inadapté.
Les erreurs 4xx demandent souvent une vérification côté client. Un 400 peut signaler un corps mal formé ou des données qui ne respectent pas ce qu'attend l'API. Un 401 concerne une authentification manquante ou invalide, tandis qu'un 403 signifie que l'accès est interdit. Un 404 vous invite à contrôler la cible demandée. Le code 429 indique qu'un trop grand nombre de requêtes a été envoyé.
Les erreurs 5xx, dont 500, renvoient à un problème côté serveur. Cela ne dispense pas le client de gérer l'échec : l'interface doit rester compréhensible et l'application ne doit pas continuer comme si les données avaient été reçues.
Pour présenter un problème avec précision à une communauté d'entraide, apprenez à inclure la méthode, l'URL fictive ou anonymisée, le statut reçu et un exemple minimal. Le guide pour poser une question technique sur un forum d'aide avec un exemple minimal donne un cadre utile pour partager les éléments pertinents sans noyer le diagnostic.
JSON est un format de données défini par une spécification dédiée. Il est couramment utilisé dans les API parce qu'il permet de représenter des objets, des listes, des chaînes, des nombres, des valeurs booléennes et des valeurs nulles. Son type de média est application/json.
Deux en-têtes méritent une attention particulière. Content-Type décrit le corps que vous envoyez. Si votre requête contient un corps JSON, indiquer Content-Type: application/json exprime que ce contenu est du JSON. Accept, lui, indique le format que le client souhaite recevoir dans la réponse. Vous pouvez ainsi annoncer Accept: application/json lorsque vous attendez une réponse JSON.
Ces en-têtes ne remplacent pas la documentation. Ils ne vous disent pas quels champs envoyer, lesquels sont obligatoires ou quelle structure le serveur retournera. Considérez-les comme une partie du contrat technique de l'échange, au même titre que la méthode et l'URL.
Avec une requête GET, aucun corps n'est envoyé dans l'exemple de ce guide. Il n'est donc pas nécessaire d'ajouter un Content-Type pour un contenu absent. En revanche, demander application/json par Accept rend l'intention de lecture explicite.
Gardez aussi une distinction importante en tête : JSON est un format de données, HTTP est le protocole qui transporte la requête et la réponse. Une réponse HTTP peut être un succès sans JSON, comme avec un 204, ou signaler une erreur avec un corps dont la structure dépend de l'API.
curl est un outil en ligne de commande qui permet d'envoyer des requêtes HTTP. Il est particulièrement pratique pour isoler un appel de l'interface d'une application et observer ce que renvoie l'API. Commencez par une lecture simple de la collection fictive d'articles :
curl -H "Accept: application/json" https://api.example.com/articles
Cette commande envoie une requête GET à l'URL indiquée et exprime une préférence pour une réponse JSON. L'API peut alors renvoyer un statut, des en-têtes et, si son contrat le prévoit, un corps représentant les articles.
Ne concluez pas à la réussite parce qu'un texte apparaît dans le terminal. Vérifiez le statut de la réponse et comparez le contenu avec la documentation. Si vous obtenez un 404, l'adresse ou la ressource demandée est probablement à revoir. Si vous obtenez un 401 ou un 403, l'appel nécessite une authentification valide ou l'accès est interdit.
L'intérêt de cet essai n'est pas de mémoriser une commande longue. Il est de comprendre qu'une requête HTTP est construite à partir d'une méthode, d'une cible et d'en-têtes, puis qu'elle doit être interprétée à partir de sa réponse.
Dans un navigateur, l'API fetch retourne une promesse. Un point souvent mal compris est que cette promesse n'est rejetée que lors d'une panne réseau. Une réponse HTTP telle que 404 ou 500 ne provoque pas, à elle seule, un rejet : la promesse est résolue avec un objet Response contenant ce statut.
Il faut donc tester response.ok ou response.status avant de considérer la requête comme réussie. La propriété response.ok est adaptée lorsque votre code veut accepter les réponses de succès et transformer les autres réponses en erreur applicative :
fetch("https://api.example.com/articles", {
headers: { Accept: "application/json" }
})
.then(async (response) => {
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
return response.json();
})
.then((articles) => console.log(articles))
.catch((error) => console.error("Erreur d'appel :", error));
Dans cet exemple, une réponse 404 ou 500 est convertie en erreur par le test de response.ok, puis prise en charge par catch. Une panne réseau rejoint également ce même chemin de traitement. En revanche, ce code suppose qu'une réponse de succès contient bien du JSON. Si la documentation annonce 204, ne lancez pas response.json() : il n'y a pas de corps à analyser.
Une gestion d'erreur utile distingue le problème sans prétendre tout résoudre automatiquement. Vous pouvez notamment prévoir les cas suivants :
204 ;La qualité d'un appel API ne se limite pas à obtenir des données lorsque tout se passe bien. Vérifier explicitement les réponses, isoler les erreurs et tester les cas attendus s'inscrivent dans les bonnes pratiques pour développeur débutant autour de Git, des tests et du débogage. Cette rigueur rend les problèmes plus faciles à reproduire et à corriger.
Certaines API demandent une authentification. Les codes de statut aident alors à comprendre la situation : 401 signale une authentification manquante ou invalide, tandis que 403 indique un accès interdit. La documentation de l'API doit préciser le mécanisme attendu, l'endroit où transmettre les informations nécessaires et les réponses possibles.
Une règle ne souffre pas d'exception pour le code exécuté dans le navigateur : ne placez jamais une clé d'API secrète dans ce code. Toute personne pouvant charger l'application peut examiner ce qui est livré au navigateur. Ne mettez pas non plus de secret dans une URL, qui peut être visible dans différents contextes techniques.
Utilisez HTTPS pour les appels à une API. Il est également préférable de concevoir votre application de manière à ce que les informations secrètes restent du côté où elles ne sont pas exposées au navigateur. Le client public doit se limiter aux informations et opérations que le contrat de l'API lui permet réellement d'utiliser.
Ces réflexes font partie d'une discipline plus large. Le dossier Cybersécurité développeur débutant : guide essentiel 2026 replace la protection des secrets, la prudence face aux entrées et les choix de développement dans une démarche cohérente.
L'authentification mérite une lecture spécifique dès que votre projet manipule des accès protégés. Pour approfondir la question, vous pouvez consulter la sécurisation d'une API avec JWT et OAuth2.
La documentation est la référence pour utiliser une API donnée. Même lorsque vous connaissez parfaitement GET, POST ou les codes 4xx, vous ne pouvez pas deviner les chemins exacts, les champs requis, les formats de réponse ou les règles propres à un service. Votre code doit suivre ce contrat plutôt que des suppositions.
Pour chaque point d'accès, relevez méthodiquement les informations suivantes :
Accept et, lorsqu'un corps est envoyé, Content-Type ;Lisez aussi les exemples avec esprit critique. Un exemple montre une situation donnée, pas toutes les réponses possibles. Votre client doit savoir réagir à un succès, à un refus d'accès, à une ressource absente, à une limitation des requêtes et à une erreur serveur.
Pour progresser, partez d'un seul appel GET documenté, reproduisez-le avec curl, puis implémentez-le avec fetch en vérifiant response.ok. Ajoutez ensuite les cas d'erreur avant de passer à des requêtes qui modifient l'état du serveur. Cette progression vous donnera des bases solides pour lire n'importe quelle API REST sans confondre URL, méthode, format et statut.
REST est un style d'architecture pour les systèmes en réseau. HTTP fournit le protocole, les méthodes, les en-têtes et les codes de statut employés pour les échanges. Une API REST utilise couramment HTTP pour exposer des ressources et leurs représentations.
Une réponse `404` ou `500` ne rejette pas automatiquement la promesse retournée par `fetch`. Le navigateur fournit alors une réponse HTTP avec un statut qui doit être examiné. Tester `response.ok` permet de transformer explicitement une réponse de non-succès en erreur applicative.
`Content-Type` décrit le corps que votre requête envoie au serveur. `Accept` indique le format que le client souhaite recevoir en réponse. Pour du JSON, le type de média est `application/json`.
Le statut `401` indique une authentification absente ou invalide. Le statut `403` indique que l'accès est interdit. Dans les deux cas, la documentation de l'API doit guider la réaction attendue côté client.
Non, une clé secrète placée dans du code exécuté par le navigateur est visible de toutes les personnes qui chargent l'application. Un secret ne doit pas non plus apparaître dans une URL. Utilisez HTTPS et conservez les informations secrètes hors du code client public.