Tout d'abord, nous verrons dans les grandes lignes ce qu'est une API — leur fonctionnement, comment les utiliser dans votre code, leur structure. Nous verrons également quelles sont les principales API et leur utilisation.
| Prérequis : | Des connaissances de base en informatique, une compréhension de base du HTML et CSS, des notions de JavaScript (voir premiers pas, briques JavaScript, objets JavaScript). |
|---|---|
| Objectif : | Vous familiariser avec les API, ce qu'elles permettent de faire, et comment les utiliser dans votre code. |
Les API (Application Programming Interfaces soit « interface de programmation d'application ») sont des constructions disponibles dans les langages de programmation pour permettre aux développeurs de créer plus facilement des fonctionnalités complexes. Elles s'occupent des parties de code plus complexes, fournissant au développeur une syntaxe plus facile à utiliser à la place.
En guise d'exemple concret, pensez à des branchements électriques dans une maison, appartement ou autre logement. Si vous souhaitez utiliser un appareil dans votre maison, il vous suffit de le brancher dans une prise et cela fonctionne. Vous n'essayez pas de le brancher directement à l'alimentation électrique — le faire serait réellement inefficace, et, si vous n'êtes pas électricien, difficile et dangereux à réaliser.
Source de l'image : Overloaded plug socket par The Clear Communication People, sur Flickr.
De la même façon, par exemple, pour programmer des graphismes en 3D, il est beaucoup plus facile de le faire en utilisant une API écrite dans un langage de haut niveau comme JavaScript ou Python, plutôt que d'essayer d'écrire du code bas niveau (comme C ou C ++) qui contrôle directement le GPU de l'ordinateur ou d'autres fonctions graphiques.
Note :
Voir aussi l'entrée du glossaire du terme API pour plus de descriptions.
Le JavaScript côté client en particulier a de nombreuses API à sa disposition — elles ne font pas partie du langage JavaScript lui-même, elles sont construites par-dessus JavaScript, offrant des super-pouvoirs supplémentaires à utiliser dans votre code. Elles appartiennent généralement à une des deux catégories :
Ci-dessus, nous avons indiqué ce qu'est une API JavaScript côté client et sa relation avec le langage JavaScript. Pour récapituler, clarifier, et apporter plus de précisions sur d'autres outils JavaScript qui existent:
Il y a un beaucoup d'API disponibles dans les navigateurs modernes. Elles permettent de faire un large éventail de choses. Vous pouvez vous en faire une petite idée en jetant un coup d'œil à la page de l'index des API MDN.
En particulier, voici les catégories d'API de navigateur les plus courantes que vous utiliserez (et que nous allons voir dans ce module plus en détail) :
<canvas> pour créer des scènes 2D et 3D. Par exemple, vous pouvez dessiner des formes comme des rectangles ou des cercles, importer une image sur le canevas, et lui appliquer un filtre sépia ou niveau de gris à l'aide de l'API Canvas ou encore créer une scène 3D complexe avec éclairage et textures en utilisant WebGL. De telles API sont souvent combinées avec d'autres API, par exemple window.requestAnimationFrame(), pour créer des boucles d'animation (faire des mises à jour continues de scènes) et ainsi créer des dessins animés et des jeux. Pour en savoir plus sur ces API, voir Dessiner des éléments graphiques.HTMLMediaElement, Web Audio API ou WebRTC, permettent de faire des choses vraiment intéressantes avec du multimédia, telles que la création de contrôles UI personnalisées pour jouer de l'audio et vidéo, l'affichage de textes comme des légendes et des sous-titres, la récupération de vidéos depuis votre webcam pour l'afficher sur l'ordinateur d'une autre personne dans une visio‑conférence ou encore l'ajout d'effets sur des pistes audio (tels que le gain, la distorsion, la balance, etc.). Pour en savoir plus sur ces API, voir API audio et vidéo.Il y a une grande variété d'API tierces ; en voici quelques-unes des plus populaires que vous allez probablement utiliser tôt ou tard :
Note :
Vous pouvez trouver des informations sur beaucoup plus d'API tierces dans le répertoire Programmable Web API.
Chaque API JavaScript fonctionne de manière légèrement différente d'une autre, mais de manière générale, elles ont des fonctionnalités communes et des thèmes similaires.
Les API interagissent avec le code en utilisant un ou plusieurs objets JavaScript, qui servent de conteneurs pour les données utilisées par l'API (contenues dans les propriétés d'objet), et la fonctionnalité rendue disponible par l'API (contenue dans des méthodes d'objet).
Note :
Si vous n'êtes pas déjà familier avec le fonctionnement des objets, vous devriez revenir en arrière et parcourir le module objets JavaScript avant de continuer.
Prenons comme exemple l'API Web Audio. Il s'agit d'une API assez complexe avec plusieurs objets. Voici les objets principaux :
AudioContext, qui représente un graphe audio qui peut être utilisé afin de manipuler la lecture audio dans le navigateur et qui possède différentes méthodes et propriétés qui sont disponibles pour manipuler ce signal audio.MediaElementAudioSourceNode, qui représente un élément <audio> contenant du son qu'on veut jouer et manipuler dans le contexte.AudioDestinationNode, qui représente la destination de l'audio, c'est-à-dire le composant physique qui sera utilisé pour produire le son (il s'agit généralement des hauts-parleurs ou des écouteurs).Alors comment ces objets interagissent-ils ? Si vous regardez notre exemple d'élément audio (regardez‑le aussi en direct), vous verrez le code suivant :
<audio src="outfoxing.mp3"></audio> <button class="paused">Play</button> <br> <input type="range" min="0" max="1" step="0.01" value="1" class="volume">
Nous incluons, tout d'abord, un élément <audio> avec lequel nous intégrons un MP3 dans la page. Nous n'incluons pas de contrôles par défaut du navigateur. Ensuite, nous incluons un <button> que nous utiliserons pour lire et arrêter la musique, et un élément <input> de type range, que nous utiliserons pour ajuster le volume de la piste en cours de lecture.
Ensuite, examinons le JavaScript de cet exemple.
Nous commençons par créer une instance AudioContext à l'intérieur de laquelle nous allons manipuler notre piste :
const AudioContext = window.AudioContext || window.webkitAudioContext; const audioCtx = new AudioContext();
Ensuite, nous créons des constantes qui stockent les références à nos éléments <audio>, <button> et <input>, et nous utilisons la méthode AudioContext.createMediaElementSource() pour créer un MediaElementAudioSourceNode représentant la source de notre audio — l'élément <audio> sera joué à partir de :
const audioElement = document.querySelector('audio');
const playBtn = document.querySelector('button');
const volumeSlider = document.querySelector('.volume');
const audioSource = audioCtx.createMediaElementSource(audioElement);
Ensuite, nous incluons deux gestionnaires d'événements qui servent à basculer entre la lecture et la pause lorsque le bouton est pressé et à réinitialiser l'affichage au début lorsque la chanson est terminée :
// lecture/pause de l'audio
playBtn.addEventListener('click', function() {
// vérifier si le contexte est en état de suspension (politique de lecture automatique)
if (audioCtx.state === 'suspended') {
audioCtx.resume();
}
// si la piste est arrêtée, la lire
if (this.getAttribute('class') === 'paused') {
audioElement.play();
this.setAttribute('class', 'playing');
this.textContent = 'Pause'
// si une piste est en cours de lecture, l'arrêter
} else if (this.getAttribute('class') === 'playing') {
audioElement.pause();
this.setAttribute('class', 'paused');
this.textContent = 'Lire';
}
});
// si la piste se termine
audioElement.addEventListener('ended', function() {
playBtn.setAttribute('class', 'paused');
playBtn.textContent = 'Lire';
});
Note :
Certains d'entre vous ont peut-être remarqué que les méthodes play() et pause() utilisées pour lire et mettre en pause la piste ne font pas partie de l'API audio Web ; elles font partie de l'API HTMLMediaElement. qui est différente mais étroitement liée.
Ensuite, nous créons un objet GainNode à l'aide de la méthode AudioContext.createGain(), qui peut être utilisé pour ajuster le volume de l'audio qui le traverse, et nous créons un autre gestionnaire d'événements qui modifie la valeur du gain (volume) du graphique audio lorsque la valeur du curseur est modifiée :
const gainNode = audioCtx.createGain();
volumeSlider.addEventListener('input', function() {
gainNode.gain.value = this.value;
});
La dernière chose à faire pour que cela fonctionne est de connecter les différents nœuds du graphe audio, ce qui est fait en utilisant la méthode AudioNode.connect() disponible sur chaque type de nœud :
audioSource.connect(gainNode).connect(audioCtx.destination);
L'audio commence dans la source, qui est ensuite connectée au nœud de gain afin que le volume de l'audio puisse être ajusté. Le nœud de gain est ensuite connecté au nœud de destination afin que le son puisse être lu sur votre ordinateur (la propriété AudioContext.destination représente ce qui est le AudioDestinationNode par défaut disponible sur le matériel de votre ordinateur, par exemple vos haut-parleurs).
Lorsque vous utilisez une API, vous devez vous assurer que vous savez où se trouve le point d'entrée de l'API. Dans l'API Web Audio, c'est assez simple — il s'agit de l'objet AudioContext, qui doit être utilisé pour effectuer toute manipulation audio quelle qu'elle soit.
L'API DOM (Document Object Model) a également un point d'entrée simple — ses fonctionnalités ont tendance à être trouvées accrochées à l'objet Document, ou à une instance d'un élément HTML que vous voulez affecter d'une manière ou d'une autre, par exemple :
const em = document.createElement('em'); // crée un nouvel élément em
const para = document.querySelector('p'); // référence à un élément p existant
em.textContent = 'Hello there!'; // donne à em du contenu textuel
para.appendChild(em); // intégre em dans le paragraphe
L'API Canvas repose également sur l'obtention d'un objet de contexte à utiliser pour manipuler les choses, bien que dans ce cas, il s'agisse d'un contexte graphique plutôt que d'un contexte audio. Son objet de contexte est créé en obtenant une référence à l'élément <canvas> sur lequel vous voulez dessiner, puis en appelant sa méthode HTMLCanvasElement.getContext() :
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
Tout ce que nous voulons faire au canevas est ensuite réalisé en appelant les propriétés et les méthodes de l'objet contexte (qui est une instance de CanvasRenderingContext2D), par exemple :
Ball.prototype.draw = function() {
ctx.beginPath();
ctx.fillStyle = this.color;
ctx.arc(this.x, this.y, this.size, 0, 2 * Math.PI);
ctx.fill();
};
Note :
Vous pouvez voir ce code en action dans notre démo de balles rebondissantes (voyez-le fonctionner en direct également).
Nous avons déjà abordé les événements plus tôt dans le cours dans notre article Introduction aux événements, qui examine en détail ce que sont les événements web côté client et comment ils sont utilisés dans votre code. Si vous n'êtes pas déjà familiarisé avec le fonctionnement des événements de l'API Web côté client, nous vous conseillons de lire cet article avant de poursuivre.
Certaines API Web ne contiennent aucun événement, mais la plupart en contiennent au moins quelques-uns. Les propriétés des gestionnaires qui nous permettent d'exécuter des fonctions lorsque des événements se produisent sont généralement répertoriées dans notre matériel de référence dans des sections distinctes intitulées « Gestionnaires d'événements ».
Nous avons déjà vu un certain nombre de gestionnaires d'événements utilisés dans notre exemple d'API audio Web ci-dessus.
Pour fournir un autre exemple, les instances de l'objet XMLHttpRequest (chacune représente une requête HTTP au serveur pour récupérer une nouvelle ressource d'un certain type) a un certain nombre d'événements disponibles sur eux, par exemple, l'événement load est déclenché lorsqu'une réponse a été renvoyée avec succès contenant la ressource demandée, et qu'elle est désormais disponible.
Le code suivant fournit un exemple simple de la façon dont cela peut être utilisé :
let requestURL = 'https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json';
let request = new XMLHttpRequest();
request.open('GET', requestURL);
request.responseType = 'json';
request.send();
request.onload = function() {
const superHeroes = request.response;
populateHeader(superHeroes);
showHeroes(superHeroes);
}
Note :
Vous pouvez voir ce code en action dans notre exemple ajax.html (voyez-le en direct également).
Les cinq premières lignes spécifient l'emplacement de la ressource que nous voulons récupérer, créent une nouvelle instance d'un objet de requête en utilisant le constructeur XMLHttpRequest(), ouvrent une requête HTTP GET pour récupérer la ressource spécifiée, spécifient que la réponse doit être envoyée au format JSON, puis envoient la requête.
La fonction du gestionnaire onload précise ensuite ce que nous faisons de la réponse. Nous savons que la réponse sera renvoyée avec succès et disponible après le déclenchement de l'événement load (sauf si une erreur s'est produite), nous sauvegardons donc la réponse contenant le JSON renvoyé dans la variable superHeroes, puis nous la passons à deux fonctions différentes pour un traitement ultérieur.
Les fonctionnalités des API Web sont soumises aux mêmes considérations de sécurité que JavaScript et les autres technologies web (par exemple same-origin policy), mais elles disposent parfois de mécanismes de sécurité supplémentaires. Par exemple, certaines des API Web les plus modernes ne fonctionneront que sur des pages servies par HTTPS, car elles transmettent des données potentiellement sensibles (par exemple Service Workers et Push).
En outre, certaines API Web demandent la permission d'être activées à l'utilisateur une fois que les appels à ces interfaces sont effectués dans votre code. À titre d'exemple, l'API Notifications API demande la permission à l'aide d'une boîte de dialogue contextuelle :
Les API Web Audio et HTMLMediaElement sont soumises à un mécanisme de sécurité appelé autoplay policy - cela signifie essentiellement que vous ne pouvez pas lire automatiquement l'audio lorsqu'une page se charge — vous devez permettre à vos utilisateurs de déclencher la lecture audio par le biais d'un contrôle comme un bouton. Cette mesure est prise parce que la lecture automatique de l'audio est généralement très ennuyeuse et que nous ne devrions pas y soumettre nos utilisateurs.
Note :
Selon la rigueur du navigateur, ces mécanismes de sécurité peuvent même empêcher l'exemple de fonctionner localement, c'est-à-dire si vous chargez le fichier d'exemple local dans votre navigateur au lieu de l'exécuter à partir d'un serveur web. Au moment de la rédaction de ce document, notre exemple d'API Web Audio ne fonctionnait pas localement sur Google Chrome — nous avons dû le télécharger sur GitHub avant qu'il ne fonctionne.
À ce stade, vous devriez avoir une bonne idée de ce que sont les API, de leur fonctionnement et de ce que vous pouvez faire avec dans votre code JavaScript. Vous avec probablement hâte de commencer à faire des choses amusantes avec des API spécifiques, alors allons-y ! Par la suite, nous verrons comment manipuler des documents avec le Document Object Model (DOM).
{{NextMenu("Learn/JavaScript/Client-side_web_APIs/Manipulating_documents", "Learn/JavaScript/Client-side_web_APIs")}}