Les APIs REST

✎ Travail n° 1 Préambule

🎯 Travail à faire :

Prendre connaisance du document Les APIs REST

💻 Travail n° 2 Prise en main de l'API OpenWeatherMap

Dans ce travail vous allez mettre en œuvre une API Web nommée “OpenWeatherMap” link.

Celle-ci va vous permettre de récupérer des données météo d’un lieu précis.

Pour accéder à cet API, une clé utilisateur doit être fournie dans la requête. Cette clé vous est remise lorsque vous vous inscrivez (gratuitement) sur le site. Dans le cadre de cette activité, vous pouvez utiliser la mienne dont la valeur est 25bcbd4cba0da77d5cb7677f5b8a5dc5. Cette clé, dans le cadre d’une souscription gratuite, permet d’effectuer au maximum 60 requêtes par minute : veillez donc à ne pas dépasser cette limite pour l’ensemble de la classe (→ l’effectif de la classe est d’environ 15 donc pas plus de 4 requêtes par étudiant et par minute, SVP).

🎯 Travail à faire :

  1. Se rendre sur l’url suivante depuis le navigateur internet et analyser la requête ainsi que la réponse du serveur :

    http://api.openweathermap.org/data/2.5/weather?q=LIsle-sur-la-Sorgue%2Cfr&appid=25bcbd4cba0da77d5cb7677f5b8a5dc5

  2. À quoi correspond le %2C dans la requête ?

  3. D’après ce qui a été dit plus haut et/ou How to start and continue calling Openweather API in the best way link, à quoi correspond la valeur appid dans la requête ?

  4. Quel élément du document JSON retourné exprime selon vous la température actuelle ?

  5. À partir de ce fragment de la doc de l’API link, modifier la requête pour obtenir les informations de température exprimées en °C plutôt qu’en °K.

  6. L’élément dt du document JSON retourné donne la date à laquelle la mesure a été effectuée. Elle est exprimée en nombre de secondes écoulées depuis le 01/01/1970 à minuit. C’est ce qu’on appelle habituellement un timestamp.

    Javascript sait gérer les timestamps mais uniquement lorsque ceux-ci sont exprimés en nombre de millisecondes (et non de secondes) écoulées depuis le 01/01/1970.

    Pour obtenir depuis Javascript une date humainement lisible correspondant à un timestamp exprimé en secondes, on peut utiliser le code suivant :

    var timestamp=2147483647; (1)
var jsDate = new Date(timestamp * 1000);  (2)
var date = jsDate.getDate() + '/' + (jsDate.getMonth()+1) + '/' + jsDate.getFullYear(); (3)
console.log(date); // affiche 19/1/2038
var heure =  jsDate.toLocaleTimeString({hour12: false}).split(' ')[0]; (4)
console.log(heure); // affiche 04:14:07
    1 on définit un timestamp
    2 on définit une date Javascript à partir du timestamp précédent en le multipliant par 1000 pour obtenir un timestamp en millisecondes
    3 on définit une chaîne de caractères qui contient la date au format jj/mm/aaaa
    4 on définit une chaîne de caractères qui contient l’heure au format hh:mm:ss

    Saisir ce code Javascript dans la console web de Firefox avec le timestamp retourné par la requête effectuée auprès du serveur OpenWeatherMap pour vérifier que la date correspond bien à celle du jour.

💻 Travail n° 3 Fonction fetch() de Javascript

On vous demande d’utiliser l'API Géo, présentée plus haut dans cette activité, pour construire une page HTML simple qui affiche quelques informations sur la commune de l’Isle sur la sorgue.

L’objectif est de s’approprier le fonctionnement de la fonction fetch de Javascript pour récupérer des données au format JSON depuis une API Web tierce afin de les intégrer à la page web.

Avant l’arrivée de la fonction fetch(), il était commun d’utiliser l’objet Javascript XMLHttpRequest pour permettre le chargement asynchrone de données destinées à modifier/mettre à jour certains fragments d’une page Web.

“Asynchrone” signifie simplement que l’utilisateur peut continuer à interagir avec la page Web pendant que la requête est traitée en arrière plan. Ceci renforce encore l’aspect dynamique de la page Web.

Cette technique — considérée comme obsolète aujourd’hui — portait le nom d’AJAX (pour Asynchronous Javascript And Xml).

🎯 Travail à faire :

  1. Créer le fichier api-geo.html avec le contenu suivant :

    <!DOCTYPE html>
<html>

<head>
  <title>API Geo</title>
  <meta charset="utf8">
</head>

<body>
  <button type="button" id="fetchTrigger">Cliquer ici pour obtenir les informations sur L'Isle sur la Sorgue</button>
  (1)

  <table>
    <thead>
      <tr>
        <th>Population</th>
        <th>Code postal</th>
        <th>Coordonnées GPS</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td id="population"></td>
        <td id="postcode"></td>
        <td id="coords"></td>
      </tr>
    </tbody>
  </table>

  <script>
    document.querySelector("#fetchTrigger").addEventListener("click", getInfo); (2)

    function getInfo() { (3)
      fetch("https://geo.api.gouv.fr/communes?nom=L'Isle-sur-la-sorgue&fields=code,codesPostaux,centre,population&format=json&geometry=centre")
        .then(response => response.json())
        .then(data => {
          // Utilisez les données JSON ici
          let infoCommune = data[0];

          document.querySelector("#population").innerHTML = infoCommune.population; (4)
          document.querySelector("#postcode").innerHTML = infoCommune.codesPostaux[0]; (4)
        })
        .catch(error => {
          // Gérez les erreurs ici
          console.error("Erreur lors de la récupération du JSON :", error);
        });
    };
  </script>
</body>

</html>
    1 Création d’un bouton HTML
    2 Attachement d’un gestionnaire d’évènement “click” au bouton → getInfo() sera appelé dès que l’utilisateur clique sur le bouton
    3 Définition du gestionnaire d’évènement du bouton.
    4 On met à jour les cellules “population” et “code postal” du tableau (<td id="population">…​</td>, <td id="postcode">…​</td>) à partir des informations reçues suite à la requête fetch().

    Noter la syntaxe d’appel de fetch() : elle utilise ce qu’on appelle une promesse( → promise) dans l’écosystème Javascript.

    Ceci permet d’enchaîner les actions à effectuer en cas de réussite (→ blocs .then(…​)) ou d’échec (bloc .catch(…​)).

  2. Charger la page dans un navigateur internet et verifier le remplissage partiel du tableau d’informations après appui sur le bouton (il doit manquer les coordonnées GPS).

  3. Compléter la fonction getInfo() pour qu’elle affiche dans la page Web les coordonnées GPS du centre de L’Isle sur la sorgue.

  4. Styliser enfin votre tableau HTML avec du code CSS pour lui donner fière allure 😉.

    Vous pourrez à cet effet utiliser des services en ligne tel que celui proposé sur le site DIV TABLE.

    api geo corrige

  5. Faire évoluer la page web pour qu’elle affiche en plus — grâce à l’API OpenWeatherMap — la température actuelle relevée à l’Isle sur la Sorgue.

    Dans un 1er temps vous vous contenterez de l’afficher sous forme de texte

    Ensuite, affichez-la dans une jauge comme celles proposées par la libraire Javascript Canvas Gauges link.

    demo gauge

    • Pour avoir accès aux fonctionnalités de la librairie gauge.js, il suffit de télécharger le fichier gauge.min.js dans le répertoire js du site Web et d’y faire référence dans le fichier html juste avant la balise fermante </body> (→ <script src="./js/gauge.min.js"></script>)

    • Canvas Gauges User Guidelink et Gauges Use Example link pourront être consultés pour personnaliser la jauge (nombre de graduations, couleurs…​).
      Cliquer sur un exemple de jauge permet d’accéder au code Javascript permettant de l’obtenir.

💻 Travail n° 4 Accès API depuis PHP

Dans le travail précédent, la récupération de données depuis OpenWeatherMap à partir du navigateur web implique d’exposer la clé d’API dans le script Javascript. Ceci n’est bien sûr pas recommandé.

Pour éviter cela, on choisira plutôt d’interroger l’API côté serveur depuis un script PHP.

Ci-dessous un exemple de code qui propose 2 alternatives — fonction native file_get_contents() et librairie cURL — pour récupérer des données depuis une API Web.

<?php
// Remplacez VOTRE_API_KEY par votre clé d'API
$apiKey = 'VOTRE_API_KEY';
$url = "http://api.openweathermap.org/data/2.5/weather?q=LIsle-sur-la-Sorgue%2Cfr&appid={$apiKey}";

// Méthode 1 : file_get_contents (si allow_url_fopen est activé)
$json = file_get_contents($url);
$data = json_decode($json, true);

// Affichage du résultat
print_r($data);

// Méthode 2 : cURL (plus universel)
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json'
]);
$result = curl_exec($ch);
curl_close($ch);

$data = json_decode($result, true);

// Affichage du résultat
print_r($data);
?>

🎯 Travail à faire :

  1. Installer et configurer le logiciel XAMPP conformément à ce qui est indiqué dans le document Installation et configuration de XAMPP

  2. Recoder la page web du travail précédent en PHP en utilisant file_get_contents() ou la librairie cURL de PHP pour afficher la température actuelle.

Résultat attendu :

trav04 screenshot

🞄  🞄  🞄