Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

Tout d'abord, nous commencerons par regarder les API depuis un haut niveau - que sont-elles, comment fonctionnent-elles, comment les utilisez-vous dans votre code, et comment sont-elles structurées? Nous verrons également quelles sont les différentes classes principales d'APIs et quel type d'utilisation elles ont.

Prérequis: Connaissances informatiques basiques, une compréhension basique de HTML and CSS, les bases de JavaScript (see premiers pas, building blocks, objets JavaScript).
Objectif: Vous familiariser avec les APIs, ce qu'ils peuvent faire, et comment vous pouvez les utiliser dans votre code.

What are APIs?

Les interfaces de programmation applicatives (API) sont des constructions disponibles dans les langages de programmation pour permettre aux développeurs de créer plus facilement des fonctionnalités complexes. Ils font abstraction du code plus complexe pour vous, en fournissant une syntaxe plus facile à utiliser à sa place.

En guise d'exemple concret, pensez à l'approvisionnement en électricité dans votre 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 dans l'alimentation électrique - le faire serait très inefficace, et si vous n'êtes pas un électricien, difficile et dangereux à essayer.

Image source: Overloaded plug socket by The Clear Communication People, on Flickr.

De la même façon, pour par exmple, programmer des graphismes en 3D, il est beaucoup plus facile de le faire en utilisant une API écrite dans un langage de plus 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.

Remarque: Voir aussi le API glossary entry pour de plus amples descriptions.

APIs en JavaScript côté client

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 plutôt construites sur le langage noyau JavaScript, vous offrant des pouvoirs supplémentaires à utiliser dans votre code JavaScript. Ils appartiennent généralement à deux catégories:

  • Browser APIs : Ils sont intégrés dans votre navigateur Web, et sont capables d'exposer des données provenant du navigateur et de l'environnement informatique environnant, et de faire des choses complexes utiles avec elles. Par exemple, l'API de géolocalisation fournit des constructions JavaScript simples pour extraire des données de localisation, par exemple, tracer votre position sur une carte Google Map. En arrière-plan, le navigateur utilise un code de plus bas niveau (par exemple C ++) pour communiquer avec le hardware GPS du périphérique (ou ce qui est disponible pour déterminer les données de position), récupérer les données de position et les renvoyer à l'environnement du navigateur pour l'utiliser dans votre code. Mais encore une fois, cette complexité est mise en abstraction par l'API.
  • Third party APIs :  Ils ne sont pas intégrés au navigateur par défaut, et vous devez généralement réupérer leur code et leurs informations depuis un site Web. Par exemple, l'API Twitter vous permet de faire des choses comme afficher vos derniers tweets sur votre site Web. Il fournit un ensemble spécial de constructions que vous pouvez utiliser pour interroger le service Twitter et retourner des informations spécifiques.

 

 

 

Relation entre JavaScript, les APIs, et les autres outils JavaScript

Ci-avant, nous avons dit ce qu'étaient les APIs JavaScript côté client, et de leur relation avec le langage JavaScript. Récapitulons cela pour rendre ceci plus clair, et mentionner également où d'autres outils JavaScript rentrent en scène:

  • JavaScript - Un langage de script de haut niveau intégré aux navigateurs qui vous permet d'implémenter des fonctionnalités sur les pages et applications Web. Notez que JavaScript est également disponible dans d'autres environnements de programmation, tels que Node. Mais ne vous en préoccupez pas pour l'instant.
  • API côté client - Constructions intégrées dans le navigateur, qui s'ajoutent au langage JavaScript et vous permettent d'implémenter plus facilement les fonctionnalités.

  • API tierces - constructions intégrées à des plateformes tierces (par exemple Twitter, Facebook) qui vous permettent d'utiliser certaines des fonctionnalités de ces plateformes dans vos propres pages Web (par exemple, afficher vos derniers Tweets sur votre page Web).

  • Bibliothèques JavaScript - Habituellement, un ou plusieurs fichiers JavaScript contenant des fonctions personnalisées que vous pouvez attacher à votre page Web pour accélérer ou activer l'écriture de fonctionnalités courantes. Des exemples incluent jQuery et Mootools.

  • Les frameworks JavaScript - L'étape supérieure aux bibliothèques, les frameworks JavaScript (par exemple Angular, React, Ember) ont tendance à être des paquets de HTML, CSS, JavaScript et autres technologies que vous installez et ensuite utilisez pour écrire une application web entière.

Que peuvent faire les APIs?

Il y a un nombre important d'APIs disponibles dans les navigateurs modernes qui vous permettent de faire une  large variété de choses dans votre code. Vous pouvez voir cela en jetant un oeil au MDN APIs index page

APIs Navigateur courants

En particulier, les catégories de Browser APIs les plus courantes que vous utiliserez (et que nous allons voir dans ce module plus en détail) sont:

  • APIs pour manipuler des documents chargés dans le navigateur. L'exemple le plus évident est l'API DOM (Document Object Model), qui vous permet de manipuler HTML et CSS - créer, supprimer et modifier du code HTML, appliquer dynamiquement de nouveaux styles à votre page, etc. Chaque fois que vous voyez une fenêtre pop-up apparaître sur une page, ou du nouveau contenu affiché par exemple, c'est le DOM en action. Découvrez en plus sur ces types d'API dans la rubrique Manipulation de documents.
  • Les APIs qui récupèrent les données du serveur pour mettre à jour des petites sections de la page Web par eux-même sont couramment utilisées. Ce détail apparemment minime a eu un impact énorme sur les performances et le comportement des sites - si vous avez juste besoin de mettre à jour une liste de stock ou une liste des nouvelles histoires disponibles, le faire sans avoir à recharger toute la page du serveur peut rendre le site ou l'application beaucoup plus réactif et "vif". Les APIs qui rendent cela possible incluent XMLHttpRequest et l'API Fetch. Vous rencontrerez aussi peut-être le terme Ajax, qui décrit cette technique. Pour en savoir plus sur ces APIs, voir Récupération de données à partir du serveur.
  • Les APIs pour dessiner et manipuler des graphiques sont maintenant largement supportées dans les navigateurs - les plus populaires sont Canvas et WebGL, qui vous permettent de mettre à jour par programmation les données de pixels contenues dans un élément HTML <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 canvas, et lui appliquer un filtre tel que sépia ou grayscale à l'aide de l'API Canvas, ou créer une scène 3D complexe avec éclairage et textures en utilisant WebGL. De tels APIs sont souvent combinés avec des APIs pour créer des boucles d'animation (telles que window.requestAnimationFrame ()) et d'autres pour faire des mises à jour continues de scènes comme des dessins animés et des jeux.
  • Les APIs Audio et Video comme HTMLMediaElement, le Web Audio API, et WebRTC vous permettent de faire des choses vraiment intéressantes avec du multimédia, telles que la création de contrôles UI personnalisés pour jouer de l'audio et de la vidéo, l'affichage de textes comme les légendes et les sous-titres, la récupération de vidéo depuis votre webcam pour être manipulée via un canvas (voir ci-dessus) ou affichée sur l'ordinateur de quelqu'un d'autre dans une conférence web, ou l'ajout d'effets à des pistes audio (tels que le gain, la distortion, la balance, etc).
  • Les APIs de périphérique sont essentiellement des APIs permettant de manipuler et de récupérer des données à partir de périphériques modernes, d'une manière utile pour les applications Web. Nous avons déjà parlé de l'API de géolocalisation accédant aux données de localisation de l'appareil afin que vous puissiez tracer votre position sur une carte. D'autres exemples incluent l'indication à l'utilisateur qu'une mise à jour utile est disponible sur une application Web via des notifications système (voir l'API Notifications) ou des vibrations (voir l'API Vibration).
  • Les APIs de stockage côté client deviennent de plus en plus répandues dans les navigateurs Web - a possibilité de stocker des données côté client est très utile si vous souhaitez créer une application qui enregistre son état entre les chargements de page, et peut-être même fonctionner lorsque le le périphérique est hors ligne. Il existe un certain nombre d'options disponibles, par exemple le simple stockage nom/valeur avec l'API Web Storage, et le stockage plus complexe de données tabulaires avec l'API IndexedDB.

APIs tierces courantes

Il y a une grande variété de Third party APIs; quelques unes des plus populaires que vous allez probablement utiliser tôt ou tard sont: 

  • L'API Twitter, qui vous permet de faire des choses comme afficher vos derniers tweets sur votre site Web.

  • L'API Google Maps vous permet de faire toutes sortes de choses avec des cartes sur vos pages web (bizarrement, cela alimente aussi Google Maps). Il s'agit maintenant d'une suite complète d'APIs, qui gère une grande variété de tâches, comme en témoigne l'API Picker Google Maps.

  • La suite d'API Facebook vous permet d'utiliser diverses parties de l'écosystème Facebook au profit de votre application, par exemple en fournissant un login d'application en utilisant le login Facebook, en acceptant les paiements via l'application, en déployant des campagnes publicitaires ciblées, etc.

  • L'API YouTube, qui vous permet d'intégrer des vidéos YouTube sur votre site, de rechercher sur YouTube, de créer des playlists, etc.

  • L'API Twilio, qui fournit un framework permettant de créer des fonctionnalités d'appel vocal et vidéo dans votre application, d'envoyer des SMS / MMS depuis vos applications, et plus encore.

Remarque: Vous pouvez trouver des informations sur beaucoup plus de 3rd party APIs sur le Programmable Web API directory.

Comment les APIs fonctionnent-elles?

Les différentes APIs Javascript fonctionnent de manières légèrement différentes, mais généralement elles ont des caractéristiques communes et des thèmes similaires de fonctionnement.

Elles sont basées sur les objets

Les APIs interagissent avec votre 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).

Remarque: Si vous n'êtes pas déjà familier avec le fonctionnement des objets, vous devriez retourner et parcourir notre module objets Javascript avant de continuer.

Retournons à l'exemple du Geolocation API - c'est un API très simple qui consiste en quelques objets simples:

  • Geolocation, qui contient trois méthodes pour contrôler la récupération des données géographiques.

  • Position, qui représente la position d'un appareil à un moment donné - contient un objet Coordinates qui contient les informations de position réelles, plus une date/heure représentant le temps donné.

  • Coordinates, qui contient beaucoup de données utiles sur la position de l'appareil, y compris la latitude et la longitude, l'altitude, la vitesse et la direction du mouvement, et plus encore.

Alors comment ces objets interagissent-ils? Si vous regarder notre exemple maps-example.html (disponible aussi en live), 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);
});

Remarque: Tout d'abord, lorsque vous chargez l'exemple ci-dessus, vous devriez recevoir une boîte de dialogue vous demandant si vous acceptez de partager votre position avec cette application (voir la section Ils ont des mécanismes de sécurité supplémentaires le cas échéant plus tard dans l'article). Vous devez accepter cela pour pouvoir tracer votre position sur la carte. Si vous ne pouvez toujours pas voir la carte, vous devrez peut-être définir vos autorisations manuellement. Vous pouvez le faire de différentes manières en fonction du navigateur que vous utilisez; par exemple, dans Firefox, allez dans> Outils > Informations sur la page > Autorisations, puis modifiez le paramètre pour Partager la position; dans Chrome, accédez à Paramètres > Confidentialité > Afficher les paramètres avancés > Paramètres de contenu, puis modifiez les paramètres de localisation.
 

Nous voulons d'abord utiliser la méthode Geolocation.getCurrentPosition() pour retourner la position actuelle de notre appareil. L'objet Geolocation du navigateur est accédé en appelant la propriété Navigator.geolocation, nous commençons donc en utilisant

navigator.geolocation.getCurrentPosition(function(position) { ... });

C'est léquivalent de quelque chose comme ça:

var myGeo = navigator.geolocation;
myGeo.getCurrentPosition(function(position) { ... });

Mais nous pouvons utiliser la syntaxe point pour chainer notre accès propriété/méthode, réduisant le nombre de lignes que nous avons à écrire.

La méthode Geolocation.getCurrentPosition () n'a qu'un seul paramètre obligatoire, qui est une fonction anonyme qui s'exécutera lorsque la position actuelle du périphérique a été récupérée avec succès. Cette fonction a elle-même un paramètre qui contient un objet Position représentant les données de position actuelles.

Remarque: Une fonction qui est prise par une autre fonction comme argument est appelée une callback function.

Ce modèle d'invocation d'une fonction seulement quand une opération a terminé est très courant dans les APIs JavaScript - s'assurer qu'une opération est terminée avant d'essayer d'utiliser les données renvoyées par l'opération dans une autre opération. Ce sont les opérations dites asynchrones. Puisque 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), nous ne pouvons 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 fonctionnerait 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 seraient pas encore disponibles. Pour cette raison, les APIs impliquant des opérations synchrones sont conçues pour utiliser des callback function, ou le système plus moderne des Promesses, qui sont maintenant disponibles dans ECMAScript 6 et sont largement utilisées dans les nouvelles API.

Nous combinons l'API Geolocation avec une API tierce - l'API Google Maps - que nous utilisons pour tracer l'emplacement renvoyé par getCurrentPosition () sur une carte Google Map. Nous mettons cette API à disposition sur notre page en y créant un lien - 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 utiliser l'API, nous créons d'abord une instance d'objet LatLng en utilisant le constructeur google.maps.LatLng (), qui prend nos valeurs Coordinates.latitude et Coordinates.longitude géolocalisées en tant que paramètres:

var latlng = new google.maps.LatLng(position.coords.latitude,position.coords.longitude);

Cet objet est lui-même défini sur la valeur de la propriété center d'un objet options que nous avons appelé myOptions. Nous créons ensuite une instance d'objet pour représenter notre carte en appelant le constructeur google.maps.Map () en lui passant deux paramètres - une référence à l'élément <div> sur lequel nous voulons afficher la carte (avec un ID de 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 maintenant.

Ce dernier bloc de code met en évidence deux modèles courants que vous verrez dans de nombreuses API. Tout d'abord, les objets API contiennent généralement des constructeurs, qui sont appelés pour créer des instances des objets que vous utiliserez pour écrire votre programme. Deuxièmement, les objets API 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 les objets options en tant que paramètres, ce qui vous permet de définir de telles options.

Remarque: Ne vous inquiétez pas si vous ne comprenez pas les détails de cet exemple immédiatement. Nous aborderons plus en détail les API tierces dans un futur article.

Elles ont des pints d'entrée identifiables

Lorsque vous utilisez une API, vous devez vous assurer de savoir où se trouve le point d'entrée pour l'API. Dans l'API Geolocation, c'est assez simple - c'est la propriété Navigator.geolocation, qui renvoie l'objet Geolocation du navigateur, dont toutes les méthodes utiles de géolocalisation sont disponibles à l'intérieur.

L'API DOM (Document Object Model) a un point d'entrée encore plus simple: ses caractéristiques ont tendance à être trouvées rattachées à l'objet Document, ou à toute instance d'un élément HTML que vous souhaitez affecter d'une certaine façon, par exemple:

var em = document.createElement('em'); // create a new em element
var para = document.querySelector('p'); // reference an existing p element
em.textContent = 'Hello there!'; // give em some text content
para.appendChild(em); // embed em inside para

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 <canvas> sur lequel vous voulez dessiner, puis en appelant sa méthode HTMLCanvasElement.getContext ():

var canvas = document.querySelector('canvas');
var ctx = canvas.getContext('2d');

Tout ce que nous voulons faire au canvas est alors obtenu en appelant les propriétés et méthodes de l'objet content (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();
};

Remarque: Vous pouvez voir ce code en action dans notre bouncing balls demo (le voir aussi en live).

Elles utilisent des événements pour manipuler les changements dans l'état

Nous avons déjà discuté des événements plus tôt dans le cours, dans notre article Introduction aux événements - cet article examine en détails ce que sont les événements Web côté client et leur utilisation dans votre code. Si vous ne vous êtes pas encore familiarisé avec le fonctionnement des événements API Web côté client, vous devriez lire cet article avant de continuer.

Certaines API Web ne contiennent aucun événement, mais certaines contiennent un nombre d'événements. Les propriétés du gestionnaire qui nous permettent d'exécuter des fonctions lorsque les événements se déclenchent sont généralement répertoriés dans notre document de référence dans des sections distinctes "Gestionnaires d'événements". À titre d'exemple simple, les instances de l'objet XMLHttpRequest (chacune représentant une requête HTTP au serveur pour récupérer une nouvelle ressource d'une certaine forme) 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 elle est maintenant disponible.

Le code suivant fournit un exemple simple de la manière d'utilisation:

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);
}

Remarque: Vous pouvez voir ce code en action dans notre exemple ajax.html (regardez-le aussi en live).

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 demande.

La fonction de gestionnaire onload spécifie ensuite ce que nous faisons avec la réponse. Nous savons que la réponse sera renvoyée avec succès et disponible après que l'événement load ait été requis (sauf si une erreur se produit), donc nous sauvegardons la réponse avec le JSON retourné dans la variable superHeroes, puis la transmettons à deux fonctions différentes pour un traitement ultérieur.

Elles ont des mécanismes de sécurité supplémentaires où cela est nécessaire

Les caractéristiques WebAPI sont soumises aux mêmes considérations de sécurité que JavaScript et d'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 (exemples: 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:

La Notifications API demande la permission de manière similaire:

Ces invites d'autorisation sont donné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 spams avec beaucoup de notifications ennuyantes.

Résumé

À ce stade, vous devriez avoir une bonne idée de ce que les API sont, comment elles fonctionnent, et ce que vous pouvez faire avec elles dans votre code JavaScript. Vous êtes probablement excité de commencer à faire des choses amusantes avec des API spécifiques, alors allons-y! Ensuite, nous verrons comment manipuler des documents avec le Document Object Model (DOM).

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : bretondev
 Dernière mise à jour par : bretondev,