API

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 :

  1. 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;
  2. 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 :

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

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

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 :

https://www.donneesquebec.ca/recherche/api/3/action/package_search?q=*:*&sort=metadata_modified%20desc

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

https://www.donneesquebec.ca/recherche/api/3/action/package_show?id=9ed153b2-4751-4e03-862f-6d4027e6f2a6

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"

}

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.

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 :

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

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

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 :

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

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%’