API : interfaces, échanges et services dans le web moderne
Dans la documentation, les tutoriels et les échanges autour du développement web, le mot API apparaît dans des contextes très différents. On parle d’API REST, d’API Web fournies par le navigateur, de Fetch API ou d’API externes. Nous rencontrons également GraphQL, les clés d’accès, les tokens ou les quotas.
Pris séparément, ces termes peuvent sembler familiers. Mais dès que nous essayons de les relier, les repères deviennent moins évidents : REST est-il une API ou une manière de l’organiser ? Fetch désigne-t-elle le service interrogé ou un moyen de l’appeler ? Quel rôle jouent alors la requête HTTP et JSON dans cet échange ?
Préambule
Cet article propose de remettre un peu d’ordre dans cet ensemble et surtout de situer clairement ces notions les unes par rapport aux autres. Les articles déjà publiés sur REST, les méthodes HTTP, le CRUD côté client ou serveur, les tokens, GraphQL ou les outils de test permettent d’approfondir chacun de ces sujets. Nous chercherons ici à les réunir dans un cadre lisible : comprendre à quoi ils servent, à quel moment ils interviennent et comment ils s’articulent dans une application web.
Pour éviter que ce parcours ne reste théorique, nous suivrons progressivement une petite application d’exploration musicale s’appuyant sur la base MusicBrainz, autour des groupes, des artistes et des mouvements musicaux au sens large. Elle interroge cette API ouverte pour effectuer une recherche, récupérer des informations structurées, puis explorer les albums, les relations ou les tags associés.
Nous ne la décortiquerons pas ligne par ligne. Chaque étape servira plutôt à isoler un mécanisme : reconnaître ce qui relève de l’API, de la requête ou des données reçues, comprendre comment lire une documentation d’API, identifier les types de requêtes, et commencer à distinguer les rôles entre client, serveur et service externe.
Une même question accompagnera ainsi toute la lecture : lorsque notre application demande quelque chose, qui dialogue avec qui, selon quelles règles, et sous quelle forme ?
Une API, c’est d’abord une interface de dialogue
Avant d’entrer dans des notions comme les requêtes ou les échanges techniques, il est important de partir de l’idée la plus simple : une API est une interface de dialogue. Autrement dit, c’est un point de contact structuré qui permet à deux programmes de communiquer sans avoir besoin de connaître leur fonctionnement interne respectif. On peut la voir comme un ensemble de règles et de formats qui définissent comment demander quelque chose et comment recevoir une réponse, un peu comme un langage commun entre deux systèmes qui ne “parlent” pas naturellement la même langue.
Une API permet à un système de rendre certaines données ou fonctionnalités accessibles à un autre, selon des règles définies, sans exposer son fonctionnement interne.
C’est une interface intermédiaire entre un programme et le système auquel il souhaite accéder. On n’accède pas directement au système ni à ses rouages internes. On passe par un point d’entrée qui filtre et organise les demandes. Certaines passent, d’autres non. Il faut formuler correctement, donner les bonnes informations, puis attendre une réponse exploitable.
C’est pour cela qu’une API ressemble à un contrat d’échange. Elle précise ce que l’on peut demander, comment le faire, quelles données transmettre, quelle réponse attendre et quelles erreurs peuvent survenir, sans exposer l’organisation interne du système. Lors d’un échange avec une API web, la réponse contient souvent des données structurées au format JSON : ce format organise les informations pour que l’application puisse les traiter, mais il ne constitue pas l’API.
Dans notre fil rouge, notre page d’exploration musicale n’a pas besoin de connaître l’organisation interne d’un système de gestion des données musicales ni la structure de la base interrogée. Elle se contente de points de dialogue bien définis : une manière de rechercher un artiste, une manière de récupérer ses informations, tandis qu’une autre interface dédiée permet d’enregistrer certains résultats dans nos favoris. C’est exactement ce rôle que jouent les API.
Toutes les API ne sont pas des API web distantes
Une confusion revient souvent lorsque l’on découvre les API : on les associe immédiatement à une adresse web que l’on interroge, à une requête HTTP, ou à un service externe qui renvoie des données. C’est une partie importante du sujet, mais ce n’est pas toute la réalité. Une API n’est pas forcément une API distante, ni même une API liée à un serveur.
Le navigateur, par exemple, expose lui-même de nombreuses API. Lorsque JavaScript modifie le contenu d’une page avec le DOM, enregistre une information avec Web Storage, dessine dans un élément Canvas, récupère une position avec Geolocation ou prépare une requête avec Fetch, il utilise déjà des interfaces fournies par l’environnement d’exécution. Ces API ne sont pas des services externes à appeler : ce sont des points d’accès intégrés au navigateur, documentés et, pour beaucoup, standardisés.
On peut d’ailleurs explorer ces interfaces directement dans la documentation de référence des Web APIs sur MDN.
Cette distinction est importante pour notre fil rouge. Avant même d’interroger une base musicale ouverte pour effectuer une recherche, notre page utilise déjà des API du navigateur. Elle peut écouter une saisie dans un champ de recherche, mettre à jour l’affichage, conserver temporairement une sélection ou déclencher une requête réseau. Ces actions paraissent simples et locales, mais elles reposent toutes sur des interfaces et des règles d’utilisation bien définies.
// Le navigateur expose le document HTML sous forme d’objet manipulable : le DOM.
const form = document.querySelector("#search-form");
const input = document.querySelector("#search-input");
// Le navigateur permet aussi d’écouter une action utilisateur.
// Ici, JavaScript réagit à la soumission du formulaire de recherche.
form.addEventListener("submit", function (event) {
event.preventDefault();
const recherche = input.value.trim();
if (!recherche) {
return;
}
// Avant même d'appeler MusicBrainz, l'application peut déjà
// mémoriser localement une information dans le navigateur.
localStorage.setItem("derniere_recherche", recherche);
});
// Ce fragment montre que JavaScript dialogue déjà avec plusieurs API du navigateur :
// - le DOM pour retrouver les éléments de la page,
// - le système d’événements pour réagir à l’utilisateur,
// - et Web Storage, via localStorage, pour conserver une donnée localement.
// L’API externe MusicBrainz n’intervient qu’ensuite.Autrement dit, il ne faut pas réduire le mot API à l’image d’un service distant qui renvoie du JSON. Une API peut permettre d’interagir avec un navigateur, une bibliothèque, un système d’exploitation, un service externe ou notre propre application. Le principe reste le même : un environnement expose certaines possibilités, et notre code les utilise en respectant les règles prévues.
Certaines API sont même directement fournies par le navigateur pour étendre ses capacités graphiques, comme la Paint API de CSS Houdini, que nous explorons plus en détail dans « Découvrez la Paint API de CSS Houdini : Libérez votre Créativité Graphique »
Les grandes familles d’API à distinguer
Une fois cette première confusion écartée, il devient plus simple de comprendre pourquoi le mot API recouvre des usages aussi différents. Il ne désigne pas une technologie unique, mais un principe d’organisation de l’accès à des fonctionnalités ou à des données. On peut ainsi distinguer trois grandes familles, selon l’origine et le rôle de l’interface.
- Les API natives du navigateur sont celles que nous utilisons déjà sans toujours les nommer. Elles permettent à JavaScript d’interagir avec la page et son environnement : manipuler le document, réagir aux événements utilisateur, stocker des données localement ou effectuer des requêtes réseau. L’API Fetch en est un exemple central, puisqu’elle fournit le mécanisme standard pour interroger des ressources externes depuis le navigateur.
- Les API externes, publiques ou contrôlées, exposent des services ou des données accessibles depuis l’extérieur. Elles peuvent fournir des catalogues, des contenus, des cartes, des données ouvertes ou des informations spécialisées. Certaines sont libres d’accès, d’autres nécessitent une clé, une authentification ou imposent des quotas d’utilisation. Dans tous les cas, elles définissent un contrat d’échange entre un client et un service distant.
- Enfin, les API applicatives internes sont celles que nous construisons nous-mêmes pour faire communiquer les différentes parties de notre système. C’est le cas lorsqu’un front-end dialogue avec un serveur que nous contrôlons, lequel peut lui-même accéder à une base de données. Dans notre fil rouge, la page d’exploration musicale interroge la MusicBrainz API externe pour rechercher des artistes, des albums ou des styles musicaux, puis s’appuie sur une API maison interne pour enregistrer les favoris.
Le mot API reste identique, mais son rôle change : il peut être une interface du navigateur, un service externe ou une interface que nous concevons nous-mêmes.
Pour approfondir ces notions, on pourra consulter la catégorie interne Requêtes & API, ou les articles tagués par APIs de Puce & Média.
Que se passe-t-il quand on utilise une API ?
Utiliser une API ne consiste pas seulement à “appeler une URL”. Avant l’appel lui-même, il faut comprendre ce que l’API met à disposition, lire sa documentation (1), identifier le bon point d’entrée (2), repérer les paramètres attendus et savoir sous quel format et selon quelle structure la réponse sera renvoyée (3). La requête n’est donc qu’un moment dans un dialogue plus large.
Dans le cas d’une API web, ce dialogue suit souvent un enchaînement assez reconnaissable. Nous préparons une demande, nous l’envoyons (4), le service la reçoit, la traite (5), puis renvoie une réponse (6). Cette réponse contient généralement des données (7), parfois un message d’erreur (8), ainsi que des indications techniques permettant de savoir comment l’échange s’est déroulé. C’est ici que l’on commence à croiser des notions comme les méthodes HTTP, les en-têtes, les codes de statut ou les formats de données comme JSON.
Dans notre explorateur musical, ce schéma suffit à situer les rôles : la page prépare la demande, MusicBrainz expose le point d’entrée, le service distant traite la recherche, puis la réponse revient sous une forme que l’interface peut exploiter. Dans la capture d’écran suivante, on voit que la recherche “space rock” envoyée à MusicBrainz renvoie une réponse JSON que l’interface peut ensuite transformer en cartes d’artistes.
Côté JavaScript, fetch() est aujourd’hui l’un des outils courants pour envoyer ce type de requête depuis le navigateur et récupérer une réponse. Mais fetch() n’est pas l’API distante elle-même : c’est une API du navigateur qui nous aide à dialoguer avec un autre service. Cette nuance est importante, car elle montre que plusieurs API peuvent déjà intervenir dans un simple échange.
On pourra prolonger cette partie avec la documentation de référence de l’API Fetch, puis avec les articles Puce & Média L’Évolution des Requêtes HTTP et des Opérations Asynchrones et Quand await casse tout : comprendre le duo async/await en profondeur (et éviter les pièges).
// Prépare la valeur saisie pour une recherche MusicBrainz.
// Ici, on supprime les espaces inutiles et on protège les guillemets
// pour éviter qu'ils ne perturbent la syntaxe de recherche.
function formatSearchValue(value) {
return value.trim().replace(/"/g, '\\"');
}
// Préparation de la recherche envoyée à MusicBrainz.
const url = new URL("https://musicbrainz.org/ws/2/artist");
url.searchParams.set("query", `artist:${formatSearchValue(searchText)}`);
url.searchParams.set("fmt", "json");
url.searchParams.set("limit", "12");
try {
// Le navigateur envoie la requête HTTP vers l’API externe.
const response = await fetch(url.toString(), {
headers: {
"Accept": "application/json"
}
});
// Si MusicBrainz répond avec une erreur HTTP, on interrompt le traitement.
if (!response.ok) {
throw new Error(`MusicBrainz a répondu avec le statut ${response.status}.`);
}
// La réponse brute est transformée en objet JavaScript exploitable.
const data = await response.json();
// L’application ne garde ensuite que la liste des artistes retournés.
const artists = normalizeArtists(data.artists || []);
} catch (error) {
console.error(error);
}
// Ce fragment montre le passage essentiel :
// - l’application construit une URL de recherche,
// - utilise fetch() pour dialoguer avec MusicBrainz,
// - transforme la réponse JSON en données JavaScript,
// - puis prévoit une gestion simple en cas d’erreur.API, requête HTTP, JSON : trois notions différentes
Lorsque nous utilisons une API web, plusieurs notions apparaissent presque en même temps. On parle d’URL, de requête, de méthode HTTP, d’en-têtes, de réponse, de JSON. Cette proximité peut donner l’impression que tous ces mots désignent la même chose. Pourtant, ils n’ont pas le même rôle. L’API organise le dialogue, la requête HTTP transporte la demande, et JSON sert souvent à structurer les données échangées.
La requête HTTP correspond au message envoyé au service selon le protocole HTTP. Elle précise vers quelle adresse nous envoyons la demande, avec quelle méthode, quels paramètres, quels en-têtes et, parfois, quel contenu dans le corps de la requête. Une API web peut décider qu’une recherche d’artiste passe par une certaine URL, qu’un ajout de favori utilise une autre route, ou qu’une suppression doit employer une méthode différente. La requête respecte alors les règles prévues par l’API. Pour approfondir ce rôle des méthodes, on pourra revenir à l’article Les Méthodes HTTP dans REST : Une approche pratique.
JSON, de son côté, n’est pas l’API. C’est un format de données très utilisé pour représenter des informations de manière structurée. Dans notre fil rouge, l’API MusicBrainz peut renvoyer une liste d’artistes, d’albums ou de tags sous forme de données structurées. Notre page peut ensuite lire ces informations et décider ce qu’elle affiche. JSON structure les informations échangées ; il ne définit pas, à lui seul, le contrat de dialogue.
Ce rôle de format de représentation des données devient encore plus clair lorsqu’on observe une API construite côté serveur. Par exemple, une application Node.js connectée à une base de données MySQL peut interroger des tables, puis renvoyer les résultats au format JSON pour les rendre exploitables par un front-end. C’est exactement ce que montre l’article Connecter Node.js à une base MySQL pour fournir des données JSON, où l’on voit comment des données stockées en base deviennent une réponse structurée consommable par une interface web.
const response = await fetch(url.toString(), {
headers: {
"Accept": "application/json"
}
});
// Ici, MusicBrainz a répondu.
// On convertit la réponse HTTP en données JavaScript issues du JSON.
const data = await response.json();
// Le JSON devient alors un objet manipulable.
// Exemple : accéder au premier artiste retourné par MusicBrainz.
const firstArtist = data.artists?.[0];
// ?. évite une erreur si aucun artiste n'a été retourné.
// https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Operators/Optional_chaining
console.log(firstArtist?.name); // nom de l’artiste
console.log(firstArtist?.id); // identifiant MusicBrainz
// fetch() sert à envoyer la requête et recevoir une réponse HTTP.
// response.json() transforme ensuite le JSON renvoyé par MusicBrainz en objet JavaScript exploitable par l’application.Cette séparation évite beaucoup de malentendus. Une API peut utiliser HTTP sans forcément renvoyer du JSON. Elle peut aussi proposer plusieurs formats ou imposer certaines règles indépendamment du format choisi. Pour comprendre une API, il faut donc regarder l’ensemble : les points d’entrée, les méthodes acceptées, les paramètres attendus, les formats de réponse, les erreurs possibles et les conditions d’accès.
Les articles Statuts et Gestion HTTP : Comprendre les Codes de Statut et Leur Utilisation Efficace et URI, URL, URN : Comprendre les bases des identifiants sur le web permettront de prolonger ces distinctions.
REST : une manière d’organiser certaines API, pas une définition de l’API
Quand on parle d’API web, le mot REST arrive très vite. Il est parfois utilisé comme s’il était synonyme d’API, alors qu’il ne définit pas ce qu’est une API en général. Il décrit plutôt un ensemble de principes permettant d’organiser certains échanges web autour de ressources, d’URL, de méthodes HTTP et de représentations de données. Pour approfondir cette approche, on pourra revenir à l’article Comprendre le concept de REST pour le développement d’applications web efficaces.
Dans une API RESTful, on cherche généralement à identifier clairement ce que l’on manipule. Un artiste, un album ou un favori peuvent devenir des ressources accessibles par des adresses cohérentes. Les méthodes HTTP servent alors à exprimer l’action attendue : récupérer une information, créer une entrée, modifier une donnée ou la supprimer. C’est précisément cette correspondance entre ressources, routes et méthodes que détaille l’article Les Méthodes HTTP dans REST : Une approche pratique.
Dans notre fil rouge, l’API maison qui enregistrerait des artistes ou des albums favoris pourrait suivre cette logique. Une route permettrait de lister les favoris, une autre d’en ajouter un, une autre encore d’en supprimer. Le front-end n’aurait pas besoin de connaître toute la base de données : il suivrait simplement les points d’entrée exposés par le serveur. Le choix des adresses aurait alors son importance, comme le montre l’article Optimisation des APIs RESTful : URLs & Bonnes pratiques.
Il faut donc garder une phrase de repère : REST n’est pas une API, mais une manière d’organiser certaines API web pour les rendre plus lisibles, cohérentes et prévisibles. L’API expose le dialogue ; REST fournit des principes pour structurer ce dialogue autour de ressources identifiées, d’URL cohérentes, de méthodes HTTP adaptées et de représentations compréhensibles.
Et GraphQL dans tout ça ?
REST n’est pas la seule manière de structurer une API. GraphQL propose une autre approche : au lieu de multiplier les points d’entrée pour chaque ressource ou chaque besoin, il permet souvent d’interroger un point d’entrée unique en décrivant précisément les champs attendus. Le client formule ainsi une requête ciblée sur les champs dont il a réellement besoin.
// Deux approches différentes pour demander des données liées.
// REST
fetch("https://api.example.com/artists/123?include=albums")
.then(r => r.json())
.then(data => console.log(data));
// GraphQL
fetch("https://api.example.com/graphql", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
query: ` { artist(id: "123") { name albums { title } } } `
})
})
.then(r => r.json())
.then(data => console.log(data));Cette logique peut devenir utile lorsque les relations entre données sont nombreuses. Dans notre fil rouge musical, une page pourrait vouloir afficher un artiste, ses albums, certains genres associés, quelques liens entre groupes proches, mais seulement une partie de ces informations selon l’écran ou le contexte. Avec GraphQL, l’intérêt est justement de pouvoir exprimer plus finement la forme de la réponse attendue, sans demander systématiquement plus de données que nécessaire.
Cela ne signifie pas que GraphQL remplace REST dans tous les cas. REST reste souvent plus lisible, plus direct et plus simple à mettre en place pour de nombreuses API. GraphQL devient surtout intéressant lorsque le client a besoin de davantage de souplesse dans les données demandées, notamment lorsque celles-ci sont fortement liées entre elles. Les deux approches ne s’opposent donc pas comme une ancienne et une nouvelle méthode : elles répondent à des situations différentes. Pour approfondir cette comparaison et voir une mise en œuvre plus concrète, on pourra revenir à l’article GraphQL : Une API Moderne qui Change la Donne.
En ce qui nous concerne, l’essentiel est de retenir ceci : une API peut être RESTful, GraphQL, ou organisée autrement. Ce choix dépend d’abord de la manière dont l’API a été conçue. Lorsque nous la consommons, nous ne décidons pas librement de changer sa forme de dialogue : nous devons suivre celle qu’elle expose dans sa documentation. Le mot API désigne le principe du dialogue, REST et GraphQL décrivent deux manières possibles de structurer ce dialogue.
Comment consommer une API depuis JavaScript ?
Dans une page web, JavaScript ne se contente pas d’envoyer une requête. Il fait le lien entre ce que l’utilisateur vient de faire, ce que l’API attend, ce que le navigateur peut envoyer, et ce que l’interface devra afficher ensuite. Son rôle est donc moins de “posséder” les données que de préparer, recevoir, vérifier et transformer ce qui circule entre la page et le service distant.
Dans notre fil rouge, l’Explorateur musical illustre directement cette position intermédiaire. Une recherche saisie dans l’interface ne peut pas être envoyée telle quelle au hasard : elle doit être nettoyée, intégrée dans une URL correctement construite, accompagnée des paramètres attendus par MusicBrainz, puis traitée lorsque la réponse revient. JavaScript assure ainsi la coordination entre l’interface, le navigateur et l’API distante.
// formatSearchValue() est une fonction propre à l’application,
// présentée précédemment pour préparer la valeur recherchée.
function formatSearchValue(value) {
return value.trim().replace(/"/g, '\\"');
}
// 1. L'interface fournit la demande de l'utilisateur.
const searchText = dom.input.value.trim();
// 2. JavaScript prépare l'adresse de l'API MusicBrainz.
const url = new URL("https://musicbrainz.org/ws/2/artist");
url.searchParams.set("query", `artist:${formatSearchValue(searchText)}`);
url.searchParams.set("fmt", "json");
url.searchParams.set("limit", "12");
try {
// 3. Le navigateur envoie la requête HTTP vers l'API externe.
const response = await fetch(url.toString(), {
headers: {
"Accept": "application/json"
}
});
if (!response.ok) {
throw new Error(`Erreur MusicBrainz : ${response.status}`);
}
// 4. La réponse JSON devient un objet JavaScript exploitable.
const data = await response.json();
// 5. Les données sont préparées puis transmises à l'affichage.
const artists = data.artists || [];
renderResults(artists);
} catch (error) {
console.error(error);
}Ce fragment montre surtout une chose : fetch() n’est qu’une étape dans un traitement plus large. Avant l’appel, JavaScript prépare la recherche. Après l’appel, il vérifie la réponse, transforme le JSON en données exploitables, puis transmet ces données à une fonction d’affichage. La documentation de l’API Fetch permet d’approfondir cette partie sans confondre l’outil utilisé par le navigateur avec l’API distante interrogée.
Le délai nécessaire pour obtenir cette réponse explique pourquoi les appels API sont souvent associés à des mécanismes asynchrones comme les Promise, et les mots-clés async et await. Une réponse distante peut arriver vite, lentement, échouer ou ne pas contenir exactement les données attendues. Le code doit donc prévoir ce temps de dialogue, au lieu de supposer que tout sera disponible immédiatement. Pour approfondir ce point, on pourra revenir à l’article Quand await casse tout : comprendre le duo async/await en profondeur (et éviter les pièges).
Ce chapitre reste volontairement limité. Il ne remplace ni un tutoriel complet sur fetch(), ni la mise en œuvre complète des opérations CRUD côté client. Il sert seulement à situer JavaScript dans la chaîne : l’interface déclenche une action, le navigateur envoie une requête, puis le script prépare les données pour l’affichage. Les articles L’Évolution des Requêtes HTTP et des Opérations Asynchrones et Mise en place d’une API RESTful CRUD : Côté Client permettront ensuite d’aller plus loin.
Comment créer sa propre API côté serveur ?
Créer sa propre API côté serveur, ce n’est pas seulement écrire quelques fichiers capables de répondre à une requête. C’est d’abord décider ce que l’application accepte d’exposer, sous quelle forme, avec quelles règles et avec quelles limites. L’API devient alors l’interface de dialogue entre le front-end, les données et la logique métier exécutée côté serveur.
Dans notre fil rouge, la page d’exploration musicale peut interroger MusicBrainz pour rechercher des artistes ou des albums, puis utiliser une API maison pour enregistrer certains résultats en favoris. Cette API interne doit définir clairement les ressources qu’elle accepte de manipuler : favoris, artistes enregistrés, albums retenus, notes personnelles ou tags ajoutés par l’utilisateur. Chaque ressource est ensuite associée à des points d’entrée, à des méthodes autorisées et à des réponses attendues.
PHP comme Node.js peuvent servir à produire ce type d’API.
- Avec PHP, une application côté serveur peut recevoir une requête, lire des paramètres, interroger une base de données, puis retourner une réponse structurée, souvent en JSON.
- Avec Node.js, le serveur applicatif peut organiser les routes, traiter les demandes et répondre dynamiquement selon les données disponibles.
Dans les deux cas, le principe reste le même : le client ne manipule pas directement la base, il passe par une interface prévue pour cela. Pour prolonger cette partie, on pourra revenir aux articles Parcours d’apprentissage web – Part VI : PHP, structurer et traiter côté serveur et Node.js : de la requête simple à une API plus souple, jointures, paramètres et affichage dynamique.
C’est cette séparation qui rend l’API utile. Le front-end formule une demande ; le serveur vérifie, traite, interroge éventuellement la base, puis répond. L’API contribue ainsi à protéger les données en contrôlant ce qui peut être fait depuis l’extérieur et fournit un cadre stable pour faire évoluer l’application sans exposer toute sa mécanique interne. La mise en œuvre complète d’une API de ce type est détaillée dans l’article Mise en place d’une API RESTful CRUD : Côté Serveur.
Clés API, tokens, quotas : quand l’accès doit être contrôlé
Toutes les API ne fonctionnent pas avec le même niveau d’ouverture. On peut les comprendre simplement à travers trois situations courantes. Ces situations ne sont pas exclusives : une API protégée par une clé ou un token peut également imposer des quotas et des règles d’usage.
- Le premier modèle est celui des API en accès libre. Elles peuvent être interrogées sans authentification ni clé. Le service peut répondre sans qu’un identifiant d’accès soit fourni. Ce type d’API est souvent utilisé pour des données publiques simples ou des services ouverts.
- Le deuxième modèle est celui des API en accès libre mais encadré. Ici, l’API reste accessible à tous, mais elle impose des limites d’usage : nombre de requêtes par seconde, par minute ou par jour, ou encore des règles d’identification de l’application. C’est le cas de nombreuses API publiques comme MusicBrainz, qui autorise les requêtes mais demande un usage raisonnable et identifiable pour éviter les abus.
- Le troisième modèle est celui des API protégées par clé ou token. Dans ce cas, l’accès nécessite une authentification. Une clé API identifie généralement l’application appelante, tandis qu’un token peut également représenter un utilisateur et être associé à des droits spécifiques : accès à certaines données, actions autorisées, ou durée de validité limitée.
Dans notre fil rouge, ces trois modèles peuvent coexister. MusicBrainz illustre l’accès libre mais encadré. Notre API maison, elle, peut relever du modèle protégé si elle gère des favoris liés à un utilisateur. Certaines API externes utilisées pour enrichir les données pourraient également nécessiter une clé d’accès.
Pour approfondir le fonctionnement des tokens et des systèmes d’authentification, on pourra consulter l’article dédié : Explorer la Gestion des Tokens pour les API.
L’essentiel à retenir est simple : toutes les API ne s’utilisent pas de la même manière, car elles n’encadrent pas toutes l’accès à leurs ressources de la même façon.
Tester une API avant de l’intégrer
Avant d’intégrer une API dans une interface, il est souvent préférable de l’interroger séparément. Cela permet de vérifier ce qu’elle renvoie réellement, comment elle réagit aux paramètres, quels codes de statut elle utilise, et quelles erreurs peuvent apparaître. Nous pouvons ainsi distinguer le fonctionnement de l’appel API des éventuels problèmes liés à son intégration ou à l’affichage dans la page.
Des outils comme Postman, Insomnia, curl ou HTTPie permettent d’envoyer des requêtes isolées, sans passer immédiatement par le code JavaScript de l’application. On peut y modifier une URL, ajouter des en-têtes, tester une méthode, observer le corps de la réponse ou comparer plusieurs scénarios. Ces tests donnent une lecture plus directe du dialogue entre le client et l’API. Pour approfondir cette pratique, on pourra revenir à l’article Postman et Insomnia : Deux Outils Incontournables pour Tester Vos APIs.
Dans notre fil rouge musical, nous pourrions tester d’abord une recherche d’artiste dans MusicBrainz avant de construire l’interface. La page MusicBrainz API / Search est particulièrement utile ici, car elle détaille les paramètres de recherche, le format de réponse, la pagination et les types d’entités interrogeables. Nous pourrions ainsi vérifier si une recherche sur un groupe de krautrock renvoie bien les données attendues, si les résultats sont nombreux, si certains champs sont absents, ou si la réponse demande un traitement particulier.
// Voici une requête de test simple, directement vérifiable dans le navigateur avant toute intégration JavaScript :
// https://musicbrainz.org/ws/2/artist?query=artist:Can&fmt=json&limit=5
/**
Endpoint : https://musicbrainz.org/ws/2/artist
Paramètre query : artist:Can
Format demandé : fmt=json
Limite : limit=5
**/
// Test manuel avant intégration dans l'interface :
// ouvrir cette URL dans le navigateur et observer le JSON retourné.
const testUrl =
"https://musicbrainz.org/ws/2/artist?query=artist:Can&fmt=json&limit=5";
// Copier cette URL dans la barre d’adresse,
// puis observer la réponse JSON retournée.
console.log(testUrl);
Tester une API à part ne remplace donc pas l’intégration finale, mais cela prépare le terrain. Une fois que nous savons ce que l’API accepte, ce qu’elle refuse et ce qu’elle renvoie, le code côté navigateur devient plus simple à écrire et à corriger. Nous ne travaillons plus à l’aveugle : nous avons déjà observé le comportement réel de l’API. Les codes de réponse pourront ensuite être analysés plus précisément avec l’article Statuts et Gestion HTTP : Comprendre les Codes de Statut et Leur Utilisation Efficace.
Lire une documentation d’API : une compétence à part entière
Savoir utiliser une API commence rarement par le code. Avant d’écrire une requête, il faut comprendre ce que la documentation met à disposition : l’adresse de base, les points d’entrée, les méthodes acceptées, les paramètres attendus, le format des réponses, les erreurs possibles et les éventuelles conditions d’accès. Cette lecture demande un peu de patience, mais elle évite de construire une intégration sur des suppositions.
Une bonne documentation d’API décrit les règles d’échange entre notre application et le service interrogé. Elle indique ce que nous pouvons demander, sous quelle forme, avec quelles limites, et ce que nous devons faire lorsque la réponse n’est pas celle attendue. Même lorsqu’un exemple de code est fourni, il ne remplace pas cette compréhension. Copier un exemple peut suffire pour tester rapidement, mais cela ne permet pas toujours d’adapter l’appel à un besoin réel.
Dans notre fil rouge musical, la documentation de MusicBrainz nous aide à répondre à des questions très concrètes : devons-nous faire une recherche, une consultation directe ou une navigation entre entités ? Quels paramètres utiliser ? Comment demander une réponse en JSON ? Comment récupérer un identifiant stable pour retrouver ensuite un artiste ou un album ? La documentation MusicBrainz API pose ce cadre général, tandis que la page MusicBrainz API / Search devient plus directement utile pour comprendre les recherches par artiste, album ou enregistrement.
Les documentations de référence ne jouent pas toutes le même rôle. Les Web APIs sur MDN accompagnent les API disponibles côté navigateur, avec des explications souvent pédagogiques et des exemples d’usage. Le Fetch Standard publié par WHATWG décrit plutôt le standard vivant qui sert de référence technique à l’API Fetch. Selon le besoin, nous ne lisons donc pas toujours le même type de document : parfois une documentation d’usage, parfois une spécification.
Les forums et espaces d’échange comme Stack Overflow, GitHub Discussions ou les canaux communautaires de MDN peuvent aider à comprendre un blocage, comparer des approches ou retrouver un problème déjà rencontré par d’autres développeurs. Mais ils ne devraient pas remplacer la documentation officielle. Une réponse ancienne peut concerner une version précédente, un contournement temporaire ou un cas particulier. Pour utiliser une API correctement, la source de référence reste toujours la documentation maintenue par le service, par l’éditeur ou par le standard concerné.
Le fil rouge en pratique : une application musicale au croisement de plusieurs API
Pour rendre ces distinctions plus concrètes, nous pouvons les observer dans l’Explorateur psychédélique, une petite application conçue comme fil rouge de cet article. Elle permet de rechercher des groupes, des artistes ou des genres musicaux dans MusicBrainz, puis d’explorer les albums, les relations et les tags associés, et de conserver certains résultats en favoris.
Cette page met en relation plusieurs niveaux d’API :
- Le navigateur fournit les interfaces locales nécessaires à l’interaction, comme le DOM, les événements, Web Storage ou Fetch.
- MusicBrainz apporte les données musicales ouvertes.
- Une API maison pourrait ensuite prendre le relais du WebStorage pour enregistrer les favoris côté serveur et les associer durablement à un utilisateur.
Dans sa version actuelle, l’application mobilise donc les API du navigateur et MusicBrainz. L’API maison représente une évolution possible du fil rouge, destinée à introduire progressivement le traitement côté serveur.
Cette vue d’ensemble permet de conserver un repère simple : une API peut venir du navigateur, d’un service externe ou de notre propre serveur. L’important est de comprendre quelle interface intervient, ce qu’elle expose, et ce que notre application peut réellement lui demander.
Conclusion : Une API comme contrat de confiance
Comprendre les API, ce n’est pas simplement ajouter un terme de plus au vocabulaire du développement web. C’est apprendre à reconnaître les points de dialogue qui relient des éléments différents : une page et un navigateur, un front-end et un serveur, une application et une plateforme, un service externe et notre propre logique métier.
Une API n’est pas une URL, une requête ou un format de données : c’est une interface qui organise un dialogue entre deux systèmes. La requête HTTP n’est qu’un des moyens de faire circuler ce dialogue lorsqu’il passe par le web. REST, GraphQL, les tokens, les quotas, les tests ou la documentation ne sont pas des notions isolées : ce sont des outils qui permettent de structurer, sécuriser, vérifier et comprendre cette communication.
La suite dépendra donc du besoin. Pour approfondir REST, HTTP, CRUD, tokens ou GraphQL, il faudra se référer aux articles spécialisés. Mais le repère essentiel reste le même : une API est un contrat d’échange, pas le code qui l’utilise ni le format qui transporte les données.
