Les APIs que nous avons vu jusqu'à présent sont intégrées dans le navigateur, mais ce n'est pas le cas de toutes. De nombreux gros sites web tels que Google Maps, Twitter, Facebook, PayPal, etc, fournissent des APIs permettant aux développeurs d'utiliser leurs données (par exemple pour afficher un flux twitter sur un blog) ou service (par exemple afficher une carte Google Maps sur un site, ou utiliser Facebook pour permettre aux utilisateurs de se connecter). Cet article compare les APIs du navigateur aux APIs tierces et montre quelques utilisations typiques de ces dernières.

Prérequis: Notions de base de JavaScript (voir premier pas, les briques JavaScript, les objets JavaScript), les notions de base des APIs côté client
Objectif: Apprendre comment les APIs fonctionnent et comment les utiliser pour améliorer vos sites web.

C'est quoi une API tierce?

Les APIs tierces sont des APIs fournies par des tierces parties, généralement des entreprises — telles que Facebook, Twitter, ou Google — pour vous permettre d'accéder à leurs fonctionnalités via JavaScript et de les utiliser sur votre propre site. Comme nous l'avons montré dans notre article introduction aux APIs du web, un des exemples les plus évidents est l'utilisation de l'API Google Maps pour afficher une carte personnalisée dans vos pages.

Regardons à nouveau notre exemple de carte (voir le code source sur GitHub; ou le voir en direct) pour illustrer en quoi les APIs tierces différent des APIs du navigateur.

Elles se situent sur des serveurs tiers

Les APIs du navigateur sont directemment intégrées au navigateur — vous pouvez y accéder immédiatement à partir de JavaScript. Par exemple, l'API Géolocalisation utilisée dans notre exemple est accédée en utilisant la propriété geolocation de l'objet Navigator, qui retourne un objet Geolocation. L'exemple suivant utilise la méthode getCurrentPosition() de cet objet pour demander la position actuelle du périphérique:

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

Les APIs tierces, d'autre part, sont situées sur un serveur tiers. Pour y accéder avec JavaScript, il faut d'abord ajouter l'API à  la page. Typiquement, cela implique d'ajouter un élément <script>, comme nous l'avons vu dans l'exemple de Google Maps:

<script type="text/javascript" src="https://maps.google.com/maps/api/js?key=AIzaSyDDuGt0E5IEGkcE6ZfrKfUtE9Ko_de66pA"></script>

À partir de ce moment là, vous pouvez utiliser les objets disponibles dans cette bibliothèque. Par exemple:

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.getElementById("map_canvas"), myOptions);
  1. Nous créons un objet LatLng avec le constructeur google.maps.LatLng(), en passant pour paramètre la latitude et la longitude de l'emplacement que nous voulons montrer — l'emplacement que nous avons récupéré plus tôt avec l'API Géolocalisation.
  2. Ensuite, nous créons un objet myOptions qui contient toutes les informations pour afficher la carte.
  3. Pour finir, nous créons réellement la carte avec le constructeur google.maps.Map(), en lui passant en paramètre l'objet d'options que nous venons de créer.

Ainsi, l'API Google Maps va tracer une carte avec les informations fournies. Le serveur de Google Maps s'occupe de tous les éléments complexes, d'afficher la carte au bon emplacement, gérer le zoom/dezoom, etc.

Note: Certaines APIs gèrent l'accès à leurs fonctionnalités légèrement différemment, demandant au développeur de faire une requête HTTP à une URL spécifique pour récupérer les données (voir Récupérer des données du serveur). C'est ce qu'on appelle une API RESTful — nous vous en donnerons un exemple plus tard dans l'article.

Les permissions sont gérées différemment

La sécurité des APIs du navigateur passe généralement par des prompts demandant à l'utilisateur de donner son autorisation (autoriser la géolocalisation par exemple), nous en avons déjà discuté dans notre premier article. Le but est que l'utilisateur sache ce qui se passe sur les sites web qu'il visite et qu'il soit moins susceptible d'être victime d'une utilisation malveillante d'une API.

Les APIs tierces ont quant à elle un système de permission légèrement différent, géré par le serveur fournissant l'API  — elles utilisent généralement des clés (/l'authentification) pour autoriser l'accès aux fonctionnalités de l'API. Regardons à nouveau l'URL de l'API Google Maps API que nous avons utilisée:

https://maps.google.com/maps/api/js?key=AIzaSyDDuGt0E5IEGkcE6ZfrKfUtE9Ko_de66pA

L'URL contient un paramètre key — le développeur de l'application doit, pour obtenir une clé, s'inscrire sur le site de l'API puis utiliser la clé dans le code pour déverouiller l'accès aux fonctionnalités de l'API. Dans le cas de Google Maps (et des autres APIs de Google), vous devez récupérer une clé auprès de Google Cloud Platform.

D'autres APIs peuvent exiger d'inclure la clé d'une manière légèrement différente (avec les entêtes HTTP par exemple), mais le principe reste le même la plupart du temps.

L'objectif d'exiger d'une clé est de ne pas laisser n'importe qui utiliser la fonctionnalité sans aucune restriction. Losque le développeur s'inscrit pour obtenir une clé, il est connu du fourniseur de l'API et des actions peuvent être mises en place s'il l'utilisee à des fins malveillantes — comme suivre l'emplacement des personnes ou essayer de spammer l'API jusqu'à ce qu'elle ne fonctionne plus. L'action la plus simple est de simplement désactiver la clé.

L'exemple Google Maps

Nous avons déjà vu les bases de l'API Google Maps, mais nous allons introduire quelques fonctionnalités supplémentaires de cette API.

Récupérer une clé

  1. Pour commencer cette section, faites une copie locale du fichier maps_start.html dans un nouveau répertoire.

  2. Ensuite, obtenez votre propre clé:

    1. Allez sur le tableau de bord de l'API Manager de Google Cloud Platform.
    2. Créer un nouveau projet si vous n'en avez pas déjà.
    3. Cliquez sur le bouton Activer API.
    4. Choisissez Google Maps JavaScript API.
    5. Cliquez sur le bouton Activer.
    6. Dans Identifants, cliquez sur Créer des identifiants, et choisissez Clé API.
    7. Copiez la clé obtenue

    Note: Récupérer des clés des APIs Google peut être un peu difficile — l'API Manager de Google Cloud  a beaucoup d'écrans différents, et le procédé à suivre peut varier légèrement selon que vous ayez déjà configuré votre compte ou non. Si vous avez des diffcultés avec cette étape, nous serons heureux de vous aider — Nous contacter.

  3. Ouvrez le fichier maps_start.html et remplacez la chaîne INSERT-YOUR-API-KEY-HERE avec votre clé (à l'intérieur de l'url du premier élément <script>).

Ajouter un marqueur personnalisé

Ajouter un marqueur (une icône) à un point sur la carte est très simple — il suffit de créer un nouveau marqueur avec le constructeur google.maps.Marker() en lui passant en paramètre un objet d'options, qui contient la position du marqueur (un objet LatLng), et l'objet Map sur lequel l'afficher.

  1. Ajoutez ce qui suit juste en dessous de la ligne var map ...:

    var marker = new google.maps.Marker({
      position: latlng,
      map: map
    });

    Maintenant, actualisez votre page et vous verrez appraître un marqueur au centre de la carte. C'est cool, mais ce n'est pas exactement un marqueur personnalisé — on utilise l'icône par défaut.

  2. Pour utiliser une icône personnalisée, vous devez passer l'emplacement de l'icône (l'URL) à utiliser au marqueur. Tout d'abord, ajoutez la ligne suivante à la suite du bloc précédant:

    var iconBase = 'https://maps.google.com/mapfiles/kml/shapes/';

    Ici, nous définissons la base de l'URL où sont stockées les icônes officielles de official Google Maps (vous pouvez également utiliser vos propres images sur votre propre serveur si vous le souhaitez).

  3. L'emplacement de l'icône est spécifié par la propriété icon de l'objet d'options. Mettez à jour le constructeur comme suit:

    var marker = new google.maps.Marker({
      position: latlng,
      icon: iconBase + 'flag_maps.png',
      map: map
    });

    Nous avons spécifié la propriété icon comme étant la concaténation de iconBase et du nom de l'icône pour créer l'URL complète. Maintenant, essayez de rafraichir votre page et vous verrez un marqueur personnalisé affiché sur votre carte!

Note: Voir Customizing a Google Map: Custom Markers (article en anglais) pour plus d'informations.

Note: Voir Map marker or Icon names pour avoir la liste des icônes disponibles et leurs noms. Le nom de l'icône est affiché lorsqu'on clique dessus, ajouter ".png" à la fin.

Afficher une popup quand le marqueur est cliqué

Un autre cas d'utilisation courant de Google Maps est d'afficher plus d'informations lorsqu'on clique sur un lieu ou sur un marqueur (les popups sont appelées des info windows dans l'API Google Maps). C'est très simple à réaliser, et nous allons voir comment.

  1. Tout d'abord, spécifiez dans une chaîne JavaScript le HTML à afficher dans la popup. Il sera affiché par l'API. Vous pouvez y mettre à peu près tout ce que vous voulez. Ajoutez la ligne suivante à la suite du constructeur google.maps.Marker():

    var contentString = '<div id="content"><h2 id="firstHeading" class="firstHeading">Custom info window</h2><p>This is a cool custom info window.</p></div>';
  2. Ensuite, créez un nouvel objet info window avec le constructeur google.maps.InfoWindow(). Ajoutez ce qui suit au-dessous de la ligne précédente:

    var infowindow = new google.maps.InfoWindow({
      content: contentString
    });

    Il y a d'autres propriétés disponibles (voir Info Windows), maisi ici nous ne faisons que spécifier la propriété content dans l'objet d'options, ce qui définit son contenu.

  3. Pour finir, ajoutez un gestionnaire d'événement pour gérer le clic sur le marqueur. Ajoutez ce qui suit après le constructeur google.maps.InfoWindow():

    marker.addListener('click', function() {
      infowindow.open(map, marker);
    });

    À l'intérieur de la fonction, nous invoquons simplement la fonction open() de l'info window, en lui donnant en paramètre la carte sur laquelle afficher la popup et le marqueur auprès duquel l'afficher.

  4. Maintenant, rechargez l'exemple dans votre navigateur et cliquez sur le marqueur!

Définir les contrôles de carte affichés

Dans le constructeur google.maps.Map(), nous avons définit l'option disableDefaultUI: true. Cela désactive les contrôles de l'interface utilisateur que vous avez habituellement sur Google Maps.

  1. Essayez de définir sa valeur à false (ou de supprimer la ligne) puis de recharger l'exemple, vous verrez que les boutons de zoom/dézoom, l'échelle, etc, sont apparus.

  2. Annulez les modifications que vous venez d'apporter.

  3. Vous pouvez afficher ou masquer les contrôles de manière plus granulaire en utiisant d'autres propriétés. Essayez d'ajouter le bloc de code suivant en dessous de disableDefaultUI: true (n'oubliez pas de mettre une virgule entre les deux):

    zoomControl: true,
    mapTypeControl: true,
    scaleControl: true,
  4. Maintenant, rechargez l'exemple pour voir les effets de ces propriétés. Vous pouvez trouver plus d'options sur l'objet MapOptions dans la page référence.

C'est tout pour l'instant — jetez un coup d'oeil à la documentation de l'API Google Maps, et amusez-vous avec!

Note: Vous pouvez trouver le code final sur GitHub (le voir en direct aussi).

Une API RESTful — NYTimes

Regardons maintenant un autre exemple d'API — l'API du New York Times. Cette API permet de récupérer les actualités du New York Times et de les afficher sur son site. Ce genre d'API est ce qu'on appelle une API RESTful — au lieu d'obtenir les données en utilisant les fonctionnalités d'une bibliothèque JavaScript, comme nous l'avons fait avec Google Maps, nous récupérons les données structurées en envoyant des requêtes HTTP à des URLs spécifiques, avec les termes de recherche et autres propriétés encodées dans l'URL (souvent comme paramètre). C'est un modèle que vous rencontrerez couramment avec les APIs.

Nous vous guiderons ci-dessous dans un exercice qui vous montrera coment utiliser l'API du NYTimes, et l'approche que vous devrez généralement suivre pour travailler avec une nouvelle API.

L'application finale vous permettra de saisir un terme de recherche avec des dates de début et de fin (facultatives), afin d'interroger l'API de recherche d'article et d'afficher les résultats obtenus.

 

Trouver la documentation

Quand vous voulez utiliser une API tierce, il est essentiel de trouver où est sa documentation, afin de connaître les fonctionnalités de l'API et savoir comment les utiliser. La documentation de l'API du NYTimes est sur https://developer.nytimes.com/.

Récupérer une clé de l'API

La plupart des APIs tierces exigent que vous utilisiez une clé, pour des raisons de sécurité et d'imputabilité des actions, comme nous l'avons déjà vu précédemment.

  1. Récupérez une API du NYTimes, sur https://developer.nytimes.com/signup — remplissez le formulaire et sélectionnez le type d'API que vous voulez utiliser, en l'occurrence "Article Search API".

  2. Attendez de recevoir votre clé par mail.

Connecter votre application à l'API

La première chose à faire est d'établir une connection entre votre application et l'API. Cela se fait soit en incluant un fichier JavaScript (comme nous l'avons fait avec l'API Google Maps), soit en requêtant l'API à des URLs spécifiques avec AJAX.

Dans le cas de cette API, vous devez requêter une URL — en passant la clé en tant que paramètre get — à chaque fois que vous voulez récupérer des données du NYTimes.

  1. Copiez localement les fichiers nytimes_start.html et nytimes.css dans un nouveau répertoire sur votre ordinateur.

  2. Dans le fichier html, trouvez la ligne suivante:

    var key = 'INSERT-YOUR-API-KEY-HERE';

    Remplacez INSERT-YOUR-API-KEY-HERE avec la clé de l'API que vous avez obtenue dans la section précédente.

  3. Ajoutez la ligne ci-dessous après le commentaire "// Event listeners to control the functionality". Cela appelle la fonction fetchResults() lorsque le formulaire est soumis (que le bouton envoyer est cliqué).

    searchForm.addEventListener('submit', submitSearch);
  4. Maintenant, ajoutez la définition de la fonction submitSearch() à la suite des lignes précédentes. Elle remet le numéro de la page à zéro puis appelle fetchResults().

    function submitSearch(e) {
      pageNumber = 0;
      fetchResults(e);
    }
    
  5. Et maintenant, ajoutez la définition de la fonction fetchResults():

    function fetchResults(e) {
      // Use preventDefault() to stop the form submitting
      e.preventDefault();
    
      // Assemble the full URL
      url = baseURL + '?api-key=' + key + '&page=' + pageNumber + '&q=' + searchTerm.value + '&fq=document_type:("article")';
    
      if(startDate.value !== '') {
        url += '&begin_date=' + startDate.value;
      };
    
      if(endDate.value !== '') {
        url += '&end_date=' + endDate.value;
      };
    }

    fetchResults() appelle preventDefault() sur l'objet événement — afin d'empêcher le formulaire d'être envoyé au serveur — puis définit l'URL à utiliser pour requêter l'API. L'URL est constituée des parties suivantes:

    • La base de l'URL (valeur stockée dans la variable baseURL).
    • Le paramètre api-key, qui spécifie la clé de l'API (stockée dans la variable key).
    • La paramètre page, qui spécifie le numéro de la page à afficher (stockée dans la variable pageNumber).
    • La paramètre q, qui spécifie le terme recherché (la valeur du champ texte searchTerm).
    • La paramètre fq, qui spécifie le type de document de nous voulons. En l'occurence, uniquement des articles.
    • Enfin, si les dates de début et de fin ont été remplies dans les champs startDate et endDate, nous les ajoutons à l'URL, à travers les paramètres begin_date et end_date respectivement.

    Ainsi, une URL complète ressemble à ceci:

    https://api.nytimes.com/svc/search/v2/articlesearch.json?api-key=4f3c267e125943d79b0a3e679f608a78&page=0&q=cats
    &fq=document_type:("article")&begin_date=20170301&end_date=20170312

    Note: Vous pouvez trouver plus de détails sur les paramètres de l'URL à utiliser dans référence Article Search API.

Note: Notre exemple valide de manière rudimentaire les données du formulaire — le terme recherché doit être ermpli pour que le formulaire puisse être soumis (on définit l'attribut required sur le champ) et les champs date ont un motif qui doit être respecté, leur valeur doit être constituée de 8 nombres (pattern="[0-9]{8}"). Voir Validation des données de formulaire pour plus de détails sur leurs fonctionnement.

Requêter des données de l'API

Maintenant que nous avons construit notre URL, nous pouvons la requêter. Pour ce faire, nous allons utiliser l'API Fetch.

Ajoutez le bloc de code suivant dans la fonction fetchResults(), juste au-dessus de l'accolade de fermeture:

// Use fetch() to make the request to the API
fetch(url).then(function(result) {
  return result.json();
}).then(function(json) {
  displayResults(json);
});

Ici, nous requêtons l'URL en passant notre variable url à fetch(), récupérons le corps de la réponse au format JSON en utilisant la fonction json(), puis passons le JSON obtenu à la fonction displayResults() pour que les données soient affichées dans notre interface utilisateur.

Afficher les données

Voyons maintenant comment afficher les données.

  • Tout d'abord, ajoutez la fonction displayResults() à la suite de la fonction fetchResults():

    function displayResults(json) {
    }
  • À l'intérieur de cette fonction, commencez par supprimer le contenu actuel de l'élément <section> — ajoutez les lignes de code suivantes:

    while (section.firstChild) {
      section.removeChild(section.firstChild);
    }
    

    Nous utilisons une boucle while pour vérifier si la <section> a un enfant, et, si c'est le cas, supprime le premier enfant. La boucle s'arrête quand la <section> n'a plus d'enfant.

  • Ensuite, assignez la variable articles à json.response.docs — il s'agit d'un tableau qui contient tous les articles retournés par la recherche. Cela nous permettra d'accéder facilement aux données, et de rendre le code plus lisible.

    var articles = json.response.docs;
    
  • L'API renvoie jusqu'à 10 articles à la fois. Si le nombre d'articles récupérés est égal à 10, alors il faut afficher la pagination; sinon, la masquer. Ajoutez le bloc de code suivant au bas de la fonction:

    if(articles.length === 10) {
      nav.style.display = 'block';
    } else {
      nav.style.display = 'none';
    }
    

    La pagination est un élément <nav> qui contient les boutons Previous 10 / Next 10 (10 précédents / 10 suivants). Nous verrons comment gérer la pagination dans la section suivante.

  • Dans le cas où aucun article n'est récupéré, ajoutez un élément <p> à la <section> pour indiquer qu'aucun résultat n'a été retourné.

    if(articles.length === 0) {
      var para = document.createElement('p');
      para.textContent = 'Aucun résultat retourné.'
      section.appendChild(para);
      return;
    }
    
  • Dans le cas contraire, nous allons afficher les articles que nous avons reçus — en créant les éléments que nous voulons afficher, définissant leur contenu et en les insérant dans le DOM au bon endroit. Ajoutez le code de code suivant:

    for(var i = 0; i < articles.length; i++) {
      var current = articles[i];
      console.log(current);
    
      // Créer tous les éléments
      var article  = document.createElement('article'),
          heading  = document.createElement('h2'),
          link     = document.createElement('a'),
          img      = document.createElement('img'),
          para1    = document.createElement('p'),
          para2    = document.createElement('p'),
          clearfix = document.createElement('div');
    
      // Définir titre
      link.href = current.web_url;
      link.textContent = current.headline.main;
    
      // Résumé
      para1.textContent = current.snippet;
    
      // Mots-clés
      para2.textContent = 'Keywords: ';
      for(var j = 0; j < current.keywords.length; j++) {
        var span = document.createElement('span');
        span.textContent += current.keywords[j].value + ' ';
        para2.appendChild(span);
      }
    
      // Image
      if(current.multimedia.length > 0) {
        img.src = 'http://www.nytimes.com/' + current.multimedia[0].url;
        img.alt = current.headline.main;
      }
      clearfix.setAttribute('class','clearfix');
    
      // Ajouter les éléments dans la page
      article.appendChild(heading);
      heading.appendChild(link);
      article.appendChild(img);
      article.appendChild(para1);
      article.appendChild(para2);
      article.appendChild(clearfix);
      section.appendChild(article);
    }

    La plupart de ces opérations sont relativement évidentes, mais quelques-unes valent la peine d'être mentionnées:

    • Nous avons utilisé une boucle for (for(var j = 0; j < current.keywords.length; j++) { ... } ) pour boucler sur tous les mots-clés associés à chaque article et les insérer dans un  <span>, que l'on ajoute à un paragraphe. Cela nous permet de modifier le style des mots-clés individuellement.
    • Nous avons utilisé une condition (if(current.multimedia.length > 0) { ... }) pour vérifier si l'article a des images associées. Si c'est le cas, nous affichons la première
    • Nous avons ajouté un élément <div> avec la classe clearfix à la fin de chaque article, cette classe est utilisé par notre CSS pour stoppper les éléments de flotter (clear float).

    Note: Pour déterminer quelles sont les propriétés de l'article que nous voulons utiliser, nous avons consulté la Référence Article Search API.

Vous pouvez essayer l'exemple maintenant, seuls les boutons de la pagination de fonctionnent pas encore.

Interragir avec la pagination

Pour que les boutons de la pagination fonctionnent, nous allons incrémenter (ou décrementer) la variable pageNumber et ré-exécuter la fonction fetchResults() pour récupérer les données de la nouvelle page. L'API du NYTimes retourne les 10 premiers produits (0 à 9) pour la page 0 (ou lorsque le paramètre page n'est pas définit), les 10 prochains (10 à 19) pour la page 1, et ainsi de suite.

Cela nous permet d'écrire une fonction de pagination très simple.

  1. À la suite de l'appel addEventListener(), ajoutez les deux lignes suivantes:

    nextBtn.addEventListener('click', nextPage);
    previousBtn.addEventListener('click', previousPage);

    Cela déclenche les fonctions nextPage() ou previousPage() quand les boutons correspondants sont cliqués.

  2. En dessous de ces lignes, ajoutez la définition des fonctions:

    function nextPage(e) {
      pageNumber++;
      fetchResults(e);
    };
    
    function previousPage(e) {
      if(pageNumber > 0) {
        pageNumber--;
      } else {
        return;
      }
      fetchResults(e);
    };

    La première fonction est simple — nous incrémentons la variable pageNumber, puis re-éxecutons la fonction fetchResults() pour afficher les résultats de la page suivante.

    La deuxième fonction fait l'inverse. Si le numéro de page est égal à 0, nous quittons simplement la fonction — puisqu'il n'existe pas de page précédente.

Note: Vous pouvez trouver le code final sur GitHub (ou voir en direct).

Exemple Youtube

Nous avons également préparé un autre exemple — voir exemple recherche vidéo YouTube. Pour ce faire, on utilise deux APIs:

Cet exemple est intéressant car il montre deux APIs tierces utilisées conjointement pour créer une application. La première est une API RESTful, tandis que la deuxième API est basée sur JavaScript (avec constructeurs, etc) — comme Google Maps. Notons tout de même que les deux APIs nécessitent d'inclure une bibliothèque JavaScript dans la page. L'API RESTful dispose de fonctions permettant de gérer les requêtes HTTP et de renvoyer les résultat, vous n'avez donc pas à les écrire vous-même en utilisant Fetch ou XHR.

Nous n'allons pas voir cet exemple pas à pas — le code source est commenté en détail pour en expliquer le fonctionnement (voir en direct).

Sommaire

Cet article vous a fournit une introduction à l'utilisation d'APIs tierces pour ajouter des fonctionnalités à vos sites web.

 

Dans ce module

Étiquettes et contributeurs liés au document

Contributeurs à cette page : a-mt
Dernière mise à jour par : a-mt,