Tout d'abord, nous survolerons le concept d'API — qu'est-ce que c'est, comment ça fonctionne, comment les utiliser dans votre code, et comment sont-elles structurées ? Nous verrons également quelles sont les principales APIs 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 APIs, ce qu'elles permettent de faire, et comment les utiliser dans votre code. |
Les APIs (Application Programming Interfaces) 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.
Image source: Overloaded plug socket by The Clear Communication People, on 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 API du glossaire pour plus de descriptions.
Le JavaScript côté client en particulier a de nombreuses APIs à 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 quelle est 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'APIs 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) :
Il y a une grande variété d'APIs 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 APIs 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 pour exemple l'API Géolocalisation — c'est une API très simple composée de quelques simples objets :
Alors comment ces objets interagissent-ils ? Si vous regardez notre exemple maps-example.html (regardez‑le aussi en direct), vous verrez le code suivant :
navigator.geolocation.getCurrentPosition(function(position) {
var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);
var myOptions = {
zoom: 8,
center: latlng,
mapTypeId: google.maps.MapTypeId.TERRAIN,
disableDefaultUI: true
}
var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions);
});
Note : Quand vous chargez l'exemple ci-dessus pour la première fois, vous devriez voir une boîte de dialogue demandant si vous acceptez de partager votre position avec cette application (voir la section {{anch ("Elles ont des mécanismes de sécurité supplémentaires si nécessaire")}} plus loin dans cet article).
Vous devez accepter pour pouvoir inscrire votre position sur la carte. Si vous ne pouvez toujours pas voir la carte, vous devrez activer l'autorisation à la main. Vous pouvez le faire de différentes manières selon le navigateur utilisé ; par exemple, dans Firefox, allez dans > Outils > Informations sur la page > Permissions, puis modifiez le paramètre Accèder à votre position ; dans Chrome, allez à Paramètres > Confidentialité > Afficher les paramètres avancés > Paramètres de contenu, puis modifiez les paramètres d'emplacement.
Pour récupérer l'objet {{domxref("Geolocation")}} du navigateur, on fait appel à {{domxref("Navigator.geolocation")}}. On se sert ensuite de la méthode {{domxref("Geolocation.getCurrentPosition()")}} pour obtenir la position actuelle de notre appareil. On commence donc avec
navigator.geolocation.getCurrentPosition(function(position) { ... });
C'est pareil que:
var myGeo = navigator.geolocation;
myGeo.getCurrentPosition(function(position) { ... });
On peut utiliser la syntaxe point pour chaîner l'accès propriété/méthode et réduire ainsi le nombre de lignes à écrire.
La méthode {{domxref("Geolocation.getCurrentPosition()")}} n'a qu'un seul paramètre obligatoire : une fonction anonyme qui s'exécute une fois que la position actuelle du périphérique a été récupérée avec succès. Cette fonction prend elle-même un paramètre, l'objet {{domxref("Position")}}, contenant les données de position actuelle.
Note : Une fonction prise en argument par une autre fonction s'appelle une fonction de rappel.
Cette manière d'appeler des fonctions seulement quand une opération est terminée, pour s'assurer de la bonne fin d'une opération avant d'utiliser les données renvoyées dans une autre opération, est très courante dans les API JavaScript. C'est ce qu'on appelle des opérations {{glossary("asynchronous", "asynchrones")}}.
Récupérer la position actuelle de l'appareil repose sur un composant externe (le GPS de l'appareil ou un autre matériel de géolocalisation), on ne peut pas garantir que cela sera fait à temps pour utiliser immédiatement les données qu'il renvoie. Par conséquent, quelque chose comme cela ne fonctionne pas :
var position = navigator.geolocation.getCurrentPosition(); var myLatitude = position.coords.latitude;
Si la première ligne n'a pas encore renvoyé son résultat, la deuxième ligne renvoie une erreur, car les données de position ne sont pas encore disponibles.
Pour cette raison, les APIs impliquant des opérations asynchrones sont conçues pour utiliser des {{glossary ("callback function","fonctions de rappel")}} ou bien le système plus moderne des Promesses — maintenant disponible dans ECMAScript 6 et largement utilisé dans les nouvelles APIs.
On combine l'API Geolocation avec une API tierce — l'API Google Maps — pour tracer l'emplacement renvoyé par getCurrentPosition() sur une carte Google Map. Pour mettre cette API à disposition sur notre page on doit l'inclure — vous trouverez cette ligne dans le code HTML:
<script type="text/javascript" src="https://maps.google.com/maps/api/js?key=AIzaSyDDuGt0E5IEGkcE6ZfrKfUtE9Ko_de66pA"></script>
Pour afficher la position de l'utilisateur sur la carte, on crée d'abord une instance d'objet LatLng avec le constructeur google.maps.LatLng(). Il prend les valeurs de géolocalisation {{domxref ("coords.latitude")}} et {{domxref ("coords.longitude")}} comme paramètres:
var latlng = new google.maps.LatLng(
position.coords.latitude,
position.coords.longitude
);
L'objet que nous avons construit est définit comme la valeur de la propriété center d'un objet d'options, myOptions. Ces options vont être utilisées pour construire la carte.
On crée une instance d'objet pour représenter notre carte en appelant le constructeur google.maps.Map() avec deux paramètres — une référence à l'élément {{htmlelement ("div")}} sur lequel on veut afficher la carte (celui avec l'ID map_canvas), et l'objet d'options que nous avons défini juste au-dessus.
var myOptions = {
zoom: 8,
center: latlng,
mapTypeId: google.maps.MapTypeId.TERRAIN,
disableDefaultUI: true
}
var map = new google.maps.Map(document.querySelector("#map_canvas"), myOptions);
Ceci fait, notre carte s'affiche.
Ce dernier bloc de code met en évidence deux modèles courants que vous verrez dans de nombreuses APIs. Tout d'abord, les objets des APIs contiennent généralement des constructeurs, qui sont appelés pour créer des instances d'objets. Ensuite, les objets APIs ont souvent plusieurs options disponibles qui peuvent être modifiées pour obtenir l'environnement exact que vous voulez pour votre programme. Les constructeurs d'API acceptent généralement des objets d'options en tant que paramètres, ce qui vous permet de définir leur comportement.
Note : Ne vous inquiétez pas si vous ne comprenez pas immédiatement le détail de cet exemple . Nous aborderons plus amplement les APIs tierces parties dans un futur article.
Lorsque vous utilisez une API, vous devez d'abord savoir quel est le point d'entrée de l'API. Dans l'API Geolocation, c'est assez simple — c'est la propriété {{domxref ("Navigator.geolocation")}} qui renvoie l'objet {{domxref ("Geolocation")}} du navigateur. Cet objet contient toutes les méthodes disponibles de géolocalisation à l'intérieur.
L'API DOM (Document Object Model) a un point d'entrée encore plus simple — ses caractéristiques sont généralement trouvées attachées à l'objet {{domxref ("Document")}}, ou à toute instance d'un élément HTML que vous souhaitez affecter d'une manière ou d'une autre. Par exemple:
var em = document.createElement('em'); // créer un nouvel élément
var para = document.querySelector('p'); // référence à un élément p existant
em.textContent = 'Hello there!'; // fournir à em un contenu textuel
para.appendChild(em); // incorporer un paragraphe dans em
D'autres API ont des points d'entrée légèrement plus complexes, impliquant souvent un contexte spécifique dans lequel le code de l'API doit être écrit. Par exemple, l'objet contextuel de l'API Canvas est créé en obtenant une référence à l'élément {{htmlelement ("canvas")}} sur lequel vous voulez dessiner, puis en appelant sa méthode {{domxref ("HTMLCanvasElement.getContext ()")}} :
var canvas = document.querySelector('canvas');
var ctx = canvas.getContext('2d');
Tout ce que nous voulons faire sur canvas est alors obtenu en appelant les propriétés et méthodes de l'objet conteneur (qui est une instance de {{domxref ("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 le code source de notre démo « balles rebondissantes » (ou voir directement).
Nous avons déjà parlé des événements plus haut dans ce cours, dans notre article Introduction aux événements — cet article explique en détail ce que sont les événements Web et leur utilisation dans votre code. Si vous ne vous êtes pas encore familiarisé avec le fonctionnement des événements de l'API Web côté client, vous devriez lire cet article avant de continuer.
Certaines API Web ne détectent pas les événements, d'autres peuvent réagir à certains. Vous pouvez généralement trouver les propriétés des APIs qui permettent de lancer des fonctions lorsque les événements surviennent dans les sections "Gestionnaires d'événements" des documents de réference des APIs.
À titre de simple exemple, les instances de l'objet XMLHttpRequest (qui représentent une requête HTTP vers le serveur pour récupérer une ressource) ont un certain nombre d'événements disponibles. Par exemple, l'événement load est déclenché lorsqu'une réponse a été retournée avec succès avec la ressource demandée, et qu'elle devient alors disponible:
var requestURL = 'https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json';
var request = new XMLHttpRequest();
request.open('GET', requestURL);
request.responseType = 'json';
request.send();
request.onload = function() {
var superHeroes = request.response;
populateHeader(superHeroes);
showHeroes(superHeroes);
}
Note : Vous pouvez voir le code source de notre exemple ajax.html (ou le voir directement).
Les cinq premières lignes définissent 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 demande.
La fonction gestionnaire onload indique ensuite ce qu'on fait avec la réponse. On sait que la réponse sera disponible dès que l'événement load est appelé (sauf si une erreur se produit), on sauvegarde donc la réponse — contenant le JSON renvoyé — dans la variable superHeroes, puis on la passe à deux fonctions différentes pour un traitement ultérieur.
Les caractéristiques des APIs Web sont soumises aux mêmes considérations de sécurité que JavaScript et des autres technologies Web (par exemple, la same-origin policy), mais elles disposent parfois de mécanismes de sécurité supplémentaires.
Par exemple, certaines des APIs Web les plus modernes ne fonctionneront que sur les pages HTTPS car elles transmettent des données potentiellement sensibles (exemple: Service Workers et Push).
En outre, certaines APIs Web demandent l'autorisation d'être activés par l'utilisateur une fois que les appels sont faits dans votre code. Par exemple, vous avez peut-être remarqué une boîte de dialogue comme celle-ci lors du chargement de notre exemple de Geolocation précédent :
De même, l'API Notifications demande une autorisation:
Ces invites d'autorisation sont affichées aux utilisateurs pour des raisons de sécurité — si elles n'étaient pas en place, alors les sites pourraient commencer à suivre secrètement votre emplacement sans que vous le sachiez, ou à vous envoyer des messages indésirables avec beaucoup de notifications ennuyantes.
À ce stade, vous devriez avoir une bonne idée de ce que sont les APIs, comment elles fonctionnent et ce que vous pouvez faire avec dans votre code JavaScript. Vous êtes probablement impatients de commencer à faire des choses amusantes avec des APIs 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")}}