L’expression « API » est l’abréviation de « Application Programming Interface » (ou en français: interface applicative de programmation). Les API sont un moyen efficace de faire communiquer deux programmes informatiques. Ainsi, une API permet d’automatiser certaines tâches dynamiques en lot et de programmer des tâches qui doivent être exécutées fréquemment.
Le portail Données Québec est soutenu par l’application Web CKAN, qui permet de cataloguer et de documenter les jeux de données, ainsi que de téléverser leurs fichiers de données d’un serveur distant vers le serveur de Données Québec. CKAN possède des API qui permettent d’interagir par programmation avec les données du portail (version CKAN 2.9 en vigueur).
Les API de CKAN permettent de répondre aux besoins des développeurs et des citoyens qui désirent consulter le contenu du portail, notamment le catalogue des jeux de données, les organisations, l’historique et les ressources qui leur sont associés.
Les interactions avec l’API se font par requêtes HTTP via des instructions qui utilisent la méthode GET ou POST. Il existe plusieurs outils permettant l’exécution des requêtes API. Les plus utilisés pour les requêtes CKAN sont les navigateurs (Chrome, Edge, Internet Explorer, Firefox, etc.), cURL, Httpie, Postman ou encore des scripts dans les langages de programmation tels que Python ou Java.
L’encodage utilisé par défaut par les API est UTF-8. L’utilisation d’autres encodages (ex. : ANSI, ISO-8859-1) peut engendrer des problèmes de compatibilité. Par exemple, les caractères latins « é » et « à » risquent d’être convertis en caractères non conformes (« Ã » et « ? »).
Il faut donc s’assurer :
- de spécifier l’encodage UTF-8 dans l’instruction de requête à l’API si les fichiers de données ne sont pas déjà encodés en UTF-8;
- que le fichier au format JSON contenant les instructions de requête à l’API soit également encodé en UTF-8, car sinon, les caractères accentués ne seront pas correctement interprétés, puisque convertis en caractères non conformes.
API génériques
Ces API permettent d’interagir avec le catalogue (organisation, fiche de métadonnées, catégorie, etc.) et les jeux de données (dataset et ressource).
Il est important de souligner que dans les API génériques, les jeux de données sont appelés « package » et non « dataset » comme dans le catalogue. Les actions des API génériques sont détaillées dans la documentation (https://docs.ckan.org/en/2.9/api/index.html).
Exemples :
Lister tous les jeux de données (package_list))
Dans un navigateur:
https://www.donneesquebec.ca/recherche/api/action/package_list
Dans une invite de commande:
curl https://www.donneesquebec.ca/recherche/api/action/package_list
Lister toutes les catégories (group_list))
Dans un navigateur:
https://www.donneesquebec.ca/recherche/api/3/action/group_list
Dans une invite de commande:
curl https://www.donneesquebec.ca/recherche/api/3/action/group_list
Faire une recherche de jeu de données (package_search)
Dans un navigateur:
Les API de CKAN permettent des requêtes précises sur plusieurs champs.
Pour trouver un jeu de données avec le mot-clé « pompier »:
https://www.donneesquebec.ca/recherche/api/3/action/package_search?q=pompier
Pour tous les jeux d’une organisation :
https://www.donneesquebec.ca/recherche/api/3/action/package_search?q=organization:ville-de-montreal
Pour la liste des jeux récemment mis à jour :
Afficher les métadonnées d’un jeu de données (package_show)
La valeur passée au paramètre id peut être soit l’identifiant du jeu (voir section « Fiche descriptive du jeu ») sur la page du jeu ou le nom du jeu dans son URL.
Dans un navigateur:
https://www.donneesquebec.ca/recherche/api/3/action/package_show?id=arbres
Création d’un nouveau jeu de données (package_create)
Dans une invite de commande:
chcp 65001 # commande à exécuter sur l’invite de commande DOS pour l’encodage UTF-8
curl -X POST https://www.donneesquebec.ca/recherche/api/3/action/package_create -H Authorization:CleAPI -d "@cheminversfichier/file.json"
file.json
{
"name":"jeu-cree-par-api-curl",
"title":"Jeu de données crée par API avec cURL",
"notes":"Description du jeu de données crée par API avec cURL",
"license_id":"cc-by",
"update_frequency":"weekly",
"private":"True",
"owner_org":"2c8496be-f549-4c92-8be3-867c948435c0",
"extras_organisation_principale":"gouvernement-du-quebec",
"author":"Secrétariat du Conseil du Trésor,DAGOLL",
"author_email":"pilote@donneesquecbec.ca",
"ext_spatial":"province-quebec",
"language":"FR_EN"
}
Mise à jour du jeu de données (package_update)
Dans cet exemple, nous modifions les paramètres le titre (title), la description (notes), la fréquence de mise à jour (update_frequency) et ajoutons le responsable (maintainer) du jeu de données «test3»
Dans une invite de commande:
chcp 65001 # commande à exécuter sur l’invite de commande DOS pour l’encodage UTF-8
curl -X POST https://www.donneesquebec.ca/recherche/api/3/action/package_update -H Authorization:CleAPI -d "@cheminversfichier/fileupdate.json"
fileupdate.json
{
"id":"4ba22983-34f1-4b87-be3d-737c92bdc77d",
"name":"test3",
"title":"Jeu de données modifier par API avec cURL",
"notes":"Description du jeu de données mise à jour par API avec cURL",
"license_id":"cc-by",
"update_frequency":"weekly",
"owner_org":"2c8496be-f549-4c92-8be3-867c948435c0",
"extras_organisation_principale":"gouvernement-du-quebec",
"author":"Secrétariat du Conseil du Trésor, DAGOLL",
"author_email":"pilote@donneesquecbec.ca",
"maintainer": "DAGOLL",
"ext_spatial":"province-quebec",
"language":"FR_EN"
}
Avec l’API package_update, il faut que toutes les valeurs obligatoires soient passées en paramètre sinon la mise à jour ne s’effectuera pas. Les paramètres non indiqués prendront les valeurs par défaut si définies. Pour changer un ou plusieurs paramètres des métadonnées d’un jeu de données sans modifier d’autres valeurs, il est préférable d’utiliser l’API package_patch.
Mise à jour du jeu de données (package_patch)
L’exemple précèdent, peut aussi être fait avec l’API package_patch
Dans une invite de commande:
chcp 65001 # commande à exécuter sur l’invite de commande DOS pour l’encodage UTF-8
curl -X POST https://www.donneesquebec.ca/recherche/api/3/action/package_patch -H Authorization:CleAPI -d "@cheminversfichier/filepatch.json"
filepatch.json
{
"id":"4ba22983-34f1-4b87-be3d-737c92bdc77d",
"title":"Jeu de données modifier par API avec cURL",
"notes":"Description du jeu de données mise à jour par API avec cURL",
"update_frequency":"weekly",
"maintainer": "DAGOLL"
}
Modification de la fréquence de mise à jour du jeu test3
Dans une invite de commade:
chcp 65001 # commande à exécuter sur l’invite de commande DOS pour l’encodage UTF-8
curl -X POST https://www.donneesquebec.ca/recherche/api/3/action/package_patch -H "Authorization:CleAPI" -F id=4ba22983-34f1-4b87-be3d-737c92bdc77d -F update_frequency=monthly
API file store
Les API fileStore permettent d’ajouter et de mettre à jour tous les types de fichiers téléversés dans CKAN. Les ressources du FileStore sont accessibles en intégralité et ne peuvent être interrogées pour en extraire ou modifier une partie (https://docs.ckan.org/en/2.9/api/index.html).
Que le fichier soit téléversé par l’API ou manuellement par l’interface utilisateur, la bonne pratique consiste à conserver le même nom de fichier lors de la mise à jour, afin de permettre aux applications développées avec ces fichiers d’aller chercher la mise à jour des données à partir de la même URL de manière automatisée.
Exemples :
Création d’une nouvelle ressource (resource_create)
Dans une invite de commande:
chcp 65001 # commande à exécuter sur l’invite de commande DOS pour l’encodage UTF-8
curl -X POST https://www.donneesquebec.ca/recherche/api/3/action/resource_create -H Authorization:CleAPI -F package_id=4ba22983-34f1-4b87-be3d-737c92bdc77d -F name="ressource_cree_api" -F url=upload -F description= "Fichier CSV contenant la liste des jeux de données" -F taille_entier=6 -F resource_type=donnees -F relidi_condon_valinc=oui -F upload=@cheminverslefichier\fichier.csv
Téléverser un nouveau fichier (resource_update)
Dans une invite de commande:
chcp 65001 # commande à exécuter sur l’invite de commande DOS pour l’encodage UTF-8
curl -X POST -H Authorization:CleAPI https://www.donneesquebec.ca/recherche/api/3/action/resource_update -F id=4ba22983-34f1-4b87-be3d-737c92bdc77d -F name=ressource_cree_api -F url=upload -F description="Fichier CSV contenant la liste des jeux de données" -F taille_entier=6 -F resource_type="donnees" -F relidi_condon_valinc=oui -F upload=@cheminversfichier\NewFile.csv
Mise à jour de la date de dernière modification (resource_patch)
Dans l’invite de commande
chcp 65001 # commande à exécuter sur l’invite de commande DOS pour l’encodage UTF-8
curl -X POST -H Authorization:CleAPI https://www.donneesquebec.ca/recherche/api/3/action/resource_patch -F id=8d0f521b-50d5-444d-a552-cf7b2d996e6a -F last_modified =2021-04-28T12:38:00
Note: Par souci de cohérence avec les autres dates du portail, il est important d’indiquer le temps en UTC et utilisé le format date AAAA-MM-JJTHH:MM:SS.
API datastore
Les API permettent d’interagir avec la base de données de CKAN (le DataStore) dans laquelle les fichiers au format CSV, XLS, XLSX des ressources sont automatiquement importés, pour pouvoir être exploités sans télécharger le fichier (https://docs.ckan.org/en/2.9/api/index.html). Il faut cependant noter que les actions apportées dans la base de données DataStore ne mettent pas à jour les versions téléchargeables (les fichiers dans le FileStore).
Exemples :
Afficher les 5 premiers éléments d'une ressource (datastore_search)
Dans un navigateur:
https://www.donneesquebec.ca/recherche/api/3/action/datastore_search?resource_id=0c8f6384-63b1-4520-8c05-25af7b69c856&limit=5
Dans une invite de commande:
curl https://www.donneesquebec.ca/recherche/api/3/action/datastore_search?resource_id=0c8f6384-63b1-4520-8c05-25af7b69c856&limit=5
Requête SQL sur une ressource dans le datastore (datastore_search_sql)
Dans un navigateur:
https://www.donneesquebec.ca/recherche/api/action/datastore_search_sql?sql=SELECT * FROM "220c8f6384-63b1-4520-8c05-25af7b69c856" WHERE "Terme_de_recherche" LIKE ‘press%’
Dans une invite de commande:
curl https://www.donneesquebec.ca/recherche/api/action/datastore_search_sql?sql=SELECT * FROM "220c8f6384-63b1-4520-8c05-25af7b69c856" WHERE "Terme_de_recherche" LIKE ‘press%’