Espace developpeurs

Cette section documente l’API de CKAN, pour les développeurs qui veulent écrire du code qui interagit avec les sites CKAN et leurs données.

L’API Action de CKAN est une puissante API de type RPC qui expose toutes les fonctionnalités de base de CKAN aux clients API. de CKAN aux clients de l’API. Toutes les fonctionnalités de base d’un site CKAN (tout ce que vous pouvez faire avec l’interface Web et plus encore) peuvent être utilisées par du code externe qui appelle l’API CKAN. code externe qui appelle l’API CKAN. Par exemple, en utilisant l’API CKAN, votre application peut:

Effectuer une requête API

Pour appeler l’API CKAN, envoyez un dictionnaire JSON dans une requête HTTP POST vers l’une des URL API de CKAN. URL de l’API CKAN. Les paramètres de la fonction API doivent être indiqués dans le dictionnaire dictionnaire JSON. CKAN renverra également sa réponse dans un dictionnaire JSON.

Une façon de poster un dictionnaire JSON à une URL est d’utiliser la ligne de commande client Curl. Par exemple, pour obtenir une liste des noms de tous les ensembles de données dans le data-explorer sur demo.ckan.org, installez curl, puis appelez la fonction API group_list en exécutant cette commande dans un terminal

curl https://demo.ckan.org/api/3/action/group_list

La réponse de CKAN ressemblera à ceci

{
    "help": "...",
    "result": [
        "data-explorer",
        "department-of-ricky",
        "geo-examples",
        "geothermal-data",
        "reykjavik",
        "skeenawild-conservation-trust"
    ],
    "success": true
}

La réponse est un dictionnaire JSON avec trois clés:

  1. "success": true or false. L’API a pour objectif de toujours renvoyer le code d’état 200 OK dans sa réponse HTTP qu’il y ait eu ou non des erreurs dans la requête. de toujours vérifier la valeur de la clé « success » dans le dictionnaire des réponses et et (si le succès est false) de vérifier la valeur de la clé "error". de la clé.

Note

Si une requête à l’API présente des problèmes de formatage majeurs, CKAN peut tout de même renvoyer une réponse HTTP avec un code d’état 409, 400 ou 500 (par ordre croissant de gravité).

  1. "result": le résultat retourné par la fonction que vous avez appelée. Le type et la valeur du résultat dépendent de la fonction que vous avez appelée. Dans le cas de la fonction Dans le cas de la fonction group_list, il s’agit d’une liste de chaînes de caractères, les noms de tous les ensembles de données qui appartiennent au groupe.

    S’il y a eu une erreur en répondant à votre requête, le dictionnaire contiendra contiendra une clé "error" avec les détails de l’erreur à la place de la clé clé "result". Un dictionnaire de réponse contenant une erreur aura l’aspect suivant ceci:

    {
    "help": "Creates a package",
    "success": false,
    "error": {
        "message": "Access denied",
        "__type": "Authorization Error"
        }
}

  2. "help": la chaîne de documentation de la fonction que vous avez appelée.

La même requête HTTP peut être effectuée en utilisant le module standard urllib2 de Python, avec ce code Python:

#!/usr/bin/env python
import urllib2
import urllib
import json
import pprint

# Effectuer la requête HTTP.
response = urllib2.urlopen('http://demo.ckan.org/api/3/action/group_list',
        data_string)
assert response.code == 200

# Utilisez le module json pour charger la réponse de CKAN dans un dictionnaire.
response_dict = json.loads(response.read())

# Vérifier le contenu de la réponse.
assert response_dict['success'] is True
result = response_dict['result']
pprint.pprint(result)

Exemple : Importation de jeux de données avec l’API CKAN

Vous pouvez ajouter des ensembles de données à l’aide de l’interface Web de CKAN, mais lorsque vous importez de nombreux ensembles de données, il est généralement plus efficace d’automatiser le processus. ensembles de données, il est généralement plus efficace d’automatiser le processus d’une manière ou d’une autre. Dans Dans cet exemple, nous allons vous montrer comment utiliser l’API CKAN pour écrire un script Python pour importer des jeux de données dans CKAN. pour importer des jeux de données dans CKAN.

#!/usr/bin/env python
import urllib2
import urllib
import json
import pprint

# Mettez les détails de l'ensemble de données que nous allons créer dans un dict.
dataset_dict = {
    'name': 'my_dataset_name',
    'notes': 'A long description of my dataset',
    'owner_org': 'org_id_or_name'
}

# Utilisez le module json pour convertir le dictionnaire en une chaîne de caractères à afficher.
data_string = urllib.quote(json.dumps(dataset_dict))

# Nous allons utiliser la fonction package_create pour créer un nouvel ensemble de données.
request = urllib2.Request(
    'http://www.my_ckan_site.com/api/action/package_create')

# La création d'un jeu de données nécessite un en-tête d'autorisation.
# Remplacez *** par votre clé API, provenant de votre compte utilisateur sur le site CKAN.
# sur lequel vous créez le jeu de données.
request.add_header('Authorization', '***')

# Effectuer la requête HTTP.
response = urllib2.urlopen(request, data_string)
assert response.code == 200

# Utilisez le module json pour charger la réponse de CKAN dans un dictionnaire.
response_dict = json.loads(response.read())
assert response_dict['success'] is True

# package_create renvoie le paquet créé comme résultat.
created_package = response_dict['result']
pprint.pprint(created_package)

API versions

Les API de CKAN sont classées par version. Si vous faites une demande à une URL d’API sans numéro de version, CKAN choisira la dernière version de l’API. numéro de version, CKAN choisira la dernière version de l’API

http://demo.ckan.org/api/action/package_list

Alternativement, vous pouvez spécifier le numéro de version de l’API souhaité dans l’URL que vous demandez:

http://demo.ckan.org/api/3/action/package_list

La version 3 est actuellement la seule version de l’API d’action.

Nous vous recommandons de spécifier le numéro d’API dans vos requêtes, car ceci car cela garantit que votre client API fonctionnera sur différents sites exécutant différentes différentes versions de CKAN (et continuera à fonctionner sur les mêmes sites, lorsque ces sites lorsque ces sites passeront à une nouvelle version de CKAN). Comme la dernière version de l’API peut changer lorsqu’un site est mis à niveau vers une nouvelle version de CKAN, ou peut différer sur différents sites exécutant différentes versions de CKAN, le résultat d’une demande d’API qui ne spécifie pas le numéro de version de l’API ne peut pas être fiable.

Authentification et jetons d’API

Certaines fonctions de l’API nécessitent une autorisation. L’API utilise les mêmes fonctions d’autorisation fonctions d’autorisation et de configuration que l’interface Web, donc si un utilisateur est autorisé à faire quelque chose dans l’interface Web, il sera également autorisé à le faire via l’API. également.

Lorsque vous appelez une fonction API qui nécessite une autorisation, vous devez vous authentifier en fournissant une clé d’authentification avec votre requête requête HTTP. À partir de CKAN 2.9, il est recommandé d’utiliser des jetons d’API. Il s’agit de des clés cryptées qui peuvent être générées manuellement à partir de l’interface utilisateur (Profil utilisateur > Gérer > Jetons d’API) ou via la fonction api_token_create(). Un utilisateur peut créer autant de jetons que nécessaire pour différentes utilisations, et révoquer un ou plusieurs jetons à tout moment. En outre, l’activation le plugin central expire_api_token permet de définir la date d’expiration d’un jeton.

Pour fournir votre jeton API dans une requête HTTP, incluez-le dans un en-tête Authorization ou X-CKAN-API-Key.

Par exemple, pour demander si vous suivez ou non l’utilisateur markw sur demo.ckan.org en utilisant curl, exécutez cette commande:

curl -H "Authorization: XXX"  https://demo.ckan.org/api/3/action/am_following_user?id=markw

(Remplacer XXX par votre jeton d’API.)

Ou, pour obtenir la liste des activités à partir de votre tableau de bord utilisateur sur demo.ckan.org, exécutez ce code Python:

request = urllib2.Request('https://demo.ckan.org/api/3/action/dashboard_activity_list')
request.add_header('Authorization', 'XXX')
response_dict = json.loads(urllib2.urlopen(request, '{}').read())

Support JSONP

Pour répondre aux scripts d’autres sites qui souhaitent accéder à l’API, les données peuvent être renvoyées au format JSONP, où les données JSON sont « complétées » par un appel de fonction. appel de fonction. La fonction est nommée dans le paramètre « callback ». Par exemple:

http://demo.ckan.org/api/3/action/package_show?id=adur_district_spending&callback=myfunction

Note

This only works for GET requests

API Examples

Tags (not in a vocabulary)

Liste de tous les mots-cles:

Top 10 des mots-cles utilisés par les jeux de données:

Tous les jeux de données qui ont le mots-cles “économie”:

Tag Vocabularies

Les 10 mots-cles et mots-cles de vocabulaire utilisés par les jeux de données

Par exemple, Facet : vocab_Topics signifie qu’il y a un vocabulaire appelé Topics, et que ses tags les plus importants sont listés sous ce vocabulaire.

Une liste de jeux de données utilisant le mots-cles “éducation” du vocabulaire “Topics” :

Téléchargement d’une nouvelle version d’un fichier de ressources

Vous pouvez utiliser le paramètre upload de la fonction resource_patch() pour télécharger une nouvelle version d’un fichier de ressources. Cela nécessite une requête multipart/form-data. Avec curl, vous pouvez le faire en utilisant la requête @file.csv:

curl -X POST  -H "Content-Type: multipart/form-data"  -H "Authorization: XXXX"  -F "id=<resource_id>" -F "upload=@updated_file.csv" https://demo.ckan.org/api/3/action/resource_patch