API et modules

Cours adapté de l'introduction à Python de Romain Tavenard.
Licence CC BY-NC-SA.

De nombreux services web fournissent des API (Application Programming Interface = Interface de programmation d'application) pour mettre des données à disposition du grand public.

On compare parfois les API à un "contrat" entre un utilisateur d'informations et un fournisseur d'informations, qui permet de définir le contenu demandé par le consommateur (l'appel) et le contenu demandé au producteur (la réponse). Par exemple, l'API d'un service de météo peut demander à l'utilisateur de fournir un code postal et au producteur de renvoyer une réponse en deux parties : la première concernant la température maximale et la seconde concernant la température minimale.

Le principe de fonctionnement de ces API est le suivant : l’utilisateur ( le client ) effectue une requête, le service web ( le serveur ) met en forme les données correspondant à la requête et les renvoie à l’utilisateur, dans un format défini à l’avance.

La manière dont le serveur récupère, met en forme et transmet les données, c'est à dire le logiciel qui tourne sur le serveur et qui implémente les fonctions de l'API, est complètement transparente pour le client: il doit uniquement savoir comment faire la demande au serveur, et sous quel format les données sont reçues.

Voici une liste ( très loin d’être exhaustive ) d’API web ( gratuites ) d’accès aux données :

OpenStreetMap : pour intégrer une carte dans son propre site web, calculer des distances/positions à la surface de la Terre, etc...
Open Data France : fournit des données publiques dans de très nombreux domaines ( éducation, justice, transports, etc...)
Open Food Facts: fournit des données relatives à l'alimentation; cette API est notamment utilisée par l'application Yuka.
...

Il existe plusieurs types d'API; nous nous intéressons ici aux API REST ( REpresentational State Transfer ), qui n'utilisent que le protocole HTTP(S) ( le même que celui utilisé pour les pages web ) pour faire les requêtes et recevoir les réponses.

Pour manipuler en Python de telles données, il faudra donc être capable :

d’envoyer une requête HTTP et de récupérer le résultat ;
de transformer le résultat en une variable Python facilement manipulable.

L'objectif de ce TP est de vous faire utiliser le module Python requests pour cela.

Vous devrez donc consulter la documentation de ce module afin de vous approprier son utilisation...

Faire des requêtes HTTP

Principe

Vous avez vu tout ça l'année dernière, en voila un bref rappel :

Vous effectuez des dizaines de requêtes chaque jour, par l’intermédiaire de votre navigateur web...
Lorsque vous entrez dans la barre d’adresse de votre navigateur l’URL suivante :


http://193.49.249.136:20180/~web/terminale/api_modules.php

votre navigateur va envoyer une requête au serveur du site du lycée pour récupérer la page que vous êtes en train de lire.
Dans cette URL, on distingue 3 sous parties :

http:// indique le protocole à utiliser pour effectuer la requête (ici HTTP);
193.49.249.136:20180 est le nom de domaine du serveur (ie. de la machine) à contacter pour obtenir une réponse; pour le site du lycée, il s'agit de l'adresse IP de ce serveur et le port utilisé;
/~web/terminale/api_modules.php indique le chemin et le nom du fichier à récupérer sur cette machine.

Exactement de la même façon, lors d’un appel à une API web, on spécifiera le protocole à utiliser, la machine à contacter, le chemin vers la ressource voulue et, en plus, un certain nombre de paramètres avec leurs valeurs, qui décriront notre requête.
Voici un exemple de requête à une API web (l’API Google Maps Directions en l’occurrence) :


https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal

On passe deux paramètres lors de la requête : origin et destination ( cette requête sert à renvoyer un itinéraire entre deux villes ).

Les paramètres sont passés "en clair" dans l'URL, il s'agit donc d'une requête GET; d'autres types de requête sont (généralement) possibles selon les API :

GET pour récupérer des données
POST pour créer de nouvelles données sur le serveur
PUT pour mettre à jour des données déjà existantes sur le serveur
DELETE pour supprimer des données

En réponse à cette requête, l’API Google Maps renvoie en fait un message d’erreur. En effet, pour être autorisé à utiliser cette API, il faut disposer d’une clé d’API et renseigner cette clé sous la forme d’un paramètre supplémentaire (nommé key dans les API Google Maps par exemple).

Pour des questions de confidentialité, nous utiliserons une API qui ne nécessite pas de clé d'accès...

L'API utilisée

Après tout, elles vous appartiennent, il est donc normal que vous puissiez consulter vos données sur nsivaugelas.

Le point d'entrée de l'API du site, c'est à dire l'URL à utiliser pour y accéder, est la suivante :

http://192.168.221.1/~web/API/api_get.php depuis le réseau du lycée,
http://193.49.249.136:20180/~web/API/api_get.php depuis l'extérieur.

Il s'agit en fait d'une version "light" de l'API du site, qui ne vous permet que de consulter les données stockées, et pas de les modifier ( ça, c'est l'API "profs" qui le permet 😎...)

Faire une requête avec le navigateur

Pour récupérer vos données sur le site, il y a deux paramètres à passer à l'API :

votre login : username=XXXXX
votre mot de passe : password=YYYYY ( en clair ! oui, pas terrible, mais il n'y a pas vraiment de données sensibles sur le site, pas vrai ? )

En suivant le schéma de l'exemple donné précédemment, faites, à l'aide de votre navigateur, une requête GET pour afficher vos données dans celui-ci.

Des requêtes avec Python

Vous pourriez faire un copier-coller de ces données du navigateur vers Python pour les exploiter, mais elles ne sont pas dans un format très explicite...de plus, il existe un module Python pour faire des requêtes HTTP, en dehors d'un navigateur : le module requests.

Ce module ne fait pas partie de la bibliothèque standard de Python, et n'est donc pas forcément installé sur vos PC.
Il est par contre disponible dans les éditeurs en ligne, pensez à charger ce module au préalable.

Écrire un script, qui utilise le module requests, pour :

envoyer une requête GET au site avec les paramètres nécessaires,
afficher le code de la réponse pour vérifier que tout s'est bien passé,
afficher vos données, sachant que le serveur les envoie au format JSON.

Le format JSON est un format de données très utilisé dans les échanges de données sur le web; pour en savoir plus sur sa structure, on peut consulter cette page.

Attention, en plus des données qui nous intéressent, il y a beaucoup d'autres données dans la réponse du serveur : il va falloir en faire le tri...

La documentation du module requests est très succincte...on pourra plutôt utiliser cette page pour des explications plus poussées.

Les questions à se poser sont notamment les suivantes :

quelle fonction du module permet de faire tel ou tel type de requête ?
quel(s) paramètre(s) prennent ces fonctions ?
que renvoient-elles ?
quelles fonctions utiliser pour extraire les données qui nous intéressent parmi toutes les informations envoyées par le serveur ?
parmi ces fonctions, quelle est la plus judicieuse à utiliser ?

Exploitation des données

Bon...on se retrouve avec pas mal de données; il va falloir maintenant les exploiter !

Pour l'exploitation/analyse de données en Python, le module de choix est Pandas; si vous ne l'avez encore jamais utilisé, voila un aperçu de ses fonctionnalités.

Ce module n'est pas non plus forcément installé sur vos machines, mais est disponible dans les éditeurs en ligne.

bien étudier la structure de données qui contient vos données.
créer un dataframe Pandas à partir de cette structure de données ( cela peut être fait directement )
afficher le dataframe ( cet affichage est tronqué, le dataframe contenant de nombreuses lignes/colonnes ).
Remarque : dans les éditeurs, vous disposez en plus d'une méthode dataframe.display() qui permet d'afficher le dataframe dans la zone de sortie graphique sous une forme un peu plus agréable.
afficher le titre des colonnes de données
certaines colonnes ne vous sont pas d'une grande utilité : créez un nouveau dataframe à partir du précédent, en ne gardant que les colonnes codename, code, jour, et clic.
trier le dataframe par date croissante
calculer la moyenne du nombre de clic(s) que vous avez fait(s) ( 1 clic = 1 appui sur le bouton 'Exécuter le code' ) avant d'envoyer votre code
déterminer, pour chaque jour où vous avez envoyé des codes, le nombre de code(s) envoyé(s) ce jour-là ( plus dur ! ).

Conclusion

Vous pouvez bien sûr consulter vos données à n'importe quel moment de l'année, l'API restera disponible.

Et vous pouvez les exploiter comme bon vous semble; pourquoi ne pas faire une petite interface graphique avec Tkinter pour les consulter ?