.. _action api:

========================================================================
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:

* Obtenez des listes formatées en JSON des jeux de données, thematiques ou autres objets:

  La liste des jeux de donnees: http://demo.ckan.org/api/3/action/package_list

  Les thematiques: http://demo.ckan.org/api/3/action/group_list

  Les mots-cles: http://demo.ckan.org/api/3/action/tag_list

* Obtenez une représentation JSON complète d'un ensemble de données, d'une ressource ou d'un autre objet:

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

  http://demo.ckan.org/api/3/action/tag_show?id=gold

  http://demo.ckan.org/api/3/action/group_show?id=data-explorer

* Recherche de jeux de donnees ou de ressources correspondant à une requête:

  http://demo.ckan.org/api/3/action/package_search?q=spending

  http://demo.ckan.org/api/3/action/resource_search?query=name:District%20Names

* Créer, mettre à jour et supprimer des ensembles de données, des ressources et d'autres objets

* Obtenez un flux d'activité des ensembles de données récemment modifiés sur un site:

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

-------------------------
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 <https://curl.haxx.se/>`_.  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é). 

2. ``"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"
            }
    }

3. ``"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.


.. _api authentication:

---------------------------------------------------------------------------------------
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 :py:func:`~ckan.logic.action.create.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:

------------
API Examples
------------


Tags (not in a vocabulary)
==========================

Liste de tous les mots-cles:

* navigateur: http://demo.ckan.org/api/3/action/tag_list
* curl: ``curl http://demo.ckan.org/api/3/action/tag_list``
* ckanapi: ``ckanapi -r http://demo.ckan.org action tag_list``

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

* navigateur: http://demo.ckan.org/api/action/package_search?facet.field=[%22tags%22]&facet.limit=10&rows=0
* curl: ``curl 'http://demo.ckan.org/api/action/package_search?facet.field=\["tags"\]&facet.limit=10&rows=0'``
* ckanapi: ``ckanapi -r http://demo.ckan.org action package_search facet.field='["tags"]' facet.limit=10 rows=0``

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

* navigateur: http://demo.ckan.org/api/3/action/package_search?fq=tags:economy
* curl: ``curl 'http://demo.ckan.org/api/3/action/package_search?fq=tags:economy'``
* ckanapi: ``ckanapi -r http://demo.ckan.org action package_search fq='tags:economy'``

Tag Vocabularies
================

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

* navigateur: http://demo.ckan.org/api/action/package_search?facet.field=[%22tags%22]&facet.limit=10&rows=0
* curl: ``curl 'http://demo.ckan.org/api/action/package_search?facet.field=\["tags"\]&facet.limit=10&rows=0'``
* ckanapi: ``ckanapi -r http://demo.ckan.org action package_search facet.field='["tags"]' facet.limit=10 rows=0``

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' :


* navigateur: https://data.hdx.rwlabs.org/api/3/action/package_search?fq=vocab_Topics:education
* curl: ``curl 'https://data.hdx.rwlabs.org/api/3/action/package_search?fq=vocab_Topics:education'``
* ckanapi: ``ckanapi -r https://data.hdx.rwlabs.org action package_search fq='vocab_Topics:education'``


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

Vous pouvez utiliser le paramètre ``upload`` de la fonction
:py:func:`~ckan.logic.action.patch.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