Tutoriel pour la création d'une API de données à partir de données existantes grâce à l'outil Datasette
Notre exemple : création d’une API pour les données des organisations de data.gouv.fr reliées à Wikidata
Datasette est un outil pour explorer et publier des données. Il permet de générer une API interactive à partir de données de toutes formes et de toutes tailles.
L'écosystème d'outils Datasette permet, entres autres, de générer très facilement et rapidement une base de données SQLite à partir de fichiers .csv, .json, ou bien à partir d'une autre base de données (MySQL, PostgreSQL, Oracle ...).
Dans ce tutoriel, nous allons construire une API avec Datasette à partir de fichiers .csv. Nous allons d'abord expliquer comment installer l'outil Datasette, ensuite nous verrons comment générer une base de données SQLite grâce à csvs-to-sqlite, et enfin nous lancerons notre serveur pour afficher notre API. Pour finir, nous expliquerons comment personnaliser notre API grâce aux métadonnées, aux templates et aux plugins. Nous allons notamment nous intéresser au plugin datasette-cluster-map qui permet d'afficher les données géographiques de nos csv sur une carte.
Démo de l'API construite avec Datasette dans ce tutoriel.
Documentation officielle en français
$ sudo apt install python3-pip $ sudo apt install python-pip
Pour installer Datasette, on lance la commande :
$ sudo -H pip3 install --prefix /usr/local datasette
Ensuite, on va installer l'outil qui nous permet de générer une base de données SQLite à partir de fichiers csv csvs-to-sqlite :
$ sudo -H pip install --prefix /usr/local csvs-to-sqlite
Pour créer la base de données à partir des fichiers csv, on lance simplement :
$ csvs-to-sqlite fichier1.csv fichier2.csv nom-de-la-base-de-données.db
On peut également utiliser des métacaractères ou des URLs :
$ csvs-to-sqlite *.csv nom-de-la-base-de-données.db
$ csvs-to-sqlite https://exemple.fr/fichier1.csv nom-de-la-base-de-données.db
Pour notre exemple, nous utilisons les données des organisations de data.gouv.fr reliées à Wikidata.
Pour lancer le serveur web, on utilise :
$ datasette nom_de_la_base_de_données
L'API est consultable à l'adresse https://localhost:8001.
Un petit aperçu du résultat :
Telles quelles, les pages web affichant l'API ne sont pas très jolies. Heureusement, nous pouvons personnaliser cette interface grâce aux métadonnées et aux templates.
À la racine du projet, on peut ajouter un fichier metadata.json qui permet de donner des informations supplémentaires pour l'API : un titre, une description, une licence, etc.
Voici à quoi peut ressembler le fichier metadata.json :
{
"title": "Organisations data.gouv.fr",
"description": "Les données des organisations de data.gouv.fr reliées à Wikidata",
"license": "Licence ouverte 2.0",
"license_url": "https://github.com/etalab/licence-ouverte/blob/master/LO.md",
"source": "www.data.gouv.fr",
"source_url": "https://www.data.gouv.fr/fr/"
}Plus d'informations sur la documentation.
Afin d'utiliser les métadonnées au lancement du serveur, on utilise la commande :
$ datasette nom_de_la_base_de_données.db --metadata metadata.json
Afin de personnaliser l'apparence de l'interface web, on peut également ajouter des templates .html et des fichiers .css.
Pour cela, on crée un répertoire templates et on y place nos templates. Les templates par défaut utilisés par datasette se trouvent dans /usr/local/lib/python3.6/dist-packages/datasette/templates.
Pour que nos templates remplacent les templates par défaut, il faut leur donner le nom adéquat :
- index.html : Pour la page d'accueil
- database.html : Pour la page d'une base de données
- table.html : Pour la page d'une table de base de données
- row.html : Pour la page d'une ligne de la base de données
- query.html : Pour la page d'une table où l'on fait des requêtes SQL
Pour lancer le serveur en utilisant ces templates, on utilise la commande :
$ datasette nom_de_la_base_de_données.db --metadata metadata.json --template-dir=templates/
En utilisant les templates créés à partir de https://template.data.gouv.fr on obtient cet affichage :
Il existe de nombreux plugins dans l'ecosystème Datasette, la liste complète est disponible ici.
Nous allons nous intéresser au plugin datasette-cluster-map qui permet d'afficher une carte dès qu'il repère une table qui contient une colonne latitude et une colonne longitude.
Pour l'exemple, je vais utiliser une liste de recensement des tiers lieux disponibles ici et créer la base de données grâce à csvs-to-sqlite comme à l'étape 2.
Attention, il faut bien veiller à ce que les colonnes concernant les coordonnées géographiques soient nommées latitude et longitude.
Pour installer le plugin, on lance la commande :
$ pip3 install datasette-cluster-map
Et c'est tout ! Maintenant lorsqu'on affiche la page de la table, on obtient une carte interactive :
Si on utilise des templates personnalisés, les choses sont un peu plus compliquées. En effet, les composants HTML de nos templates n'ont pas forcément les mêmes identifiants que ceux qui étaient par défaut créés par Datasette.
Il faut d'abord récupérer le script datasette-cluster-map.js disponible ici.
Ensuite, il faut modifier ce script pour mettre le nom de vos éléments HTML ( 3 lignes à modifier ):
...
6 document.querySelectorAll('.table th'),
...
122 let facets= document.querySelector('.suggested-facets');
123 facets.parentNode.insertBefore(el, facets.nextSibling);
...Remarque : si vous utilisez les templates fournis par ce tutoriel vous pouvez simplement récupérer le fichier datasette-cluster-map.js dans plugins/.
Pour intégrer le script à notre site web, on va d'abord l'héberger sur internet, par exemple sur yourjavascript.com .
On ajoute le lien obtenu dans notre fichier templates/header.html :
<script type="text/javascript" src="http://yourjavascript.com/18830190220/datasette-cluster-map.js"></script>Et voilà le résultat :
Comme on a pu le voir, Datasette est un outil facile à prendre en main, et qui permet de générer une API avec de nombreuses fonctionnalités en très peu de temps. Grâce aux systèmes de templates et de plugins, il est possible de créer des APIs très complètes pour correspondre à n'importe quels types de données. La limite de cet outil est qu'il ne permet pas de créer des APIs dont les données sont modifiables par les utilisateurs. Pour créer une telle API, on pourrait par exemple utiliser API Platform. Enfin, si l'on ne dispose pas de serveurs pour héberger notre API, on peut utiliser Netlify qui permet d'héberger gratuitement des applications web.
2019 Direction interministérielle du numérique et du système
d'information et de communication de l'État.
2019 Les contributeurs accessibles via l'historique du dépôt.
Les contenus accessibles dans ce dépôt sont placés sous Licence
Ouverte 2.0. Vous êtes libre de réutiliser les contenus de ce dépôt
sous les conditions précisées dans cette licence.
Ce document est écrit par Gaëlle Marais à Etalab.