API Examples

Using the API

Here is an example of web service requests using the Javascript client. You can found a list of CKAN clients here: https://github.com/ckan/ckan/wiki/CKAN-API-Clients The following examples use NodeJs. Be sure to have the latest version installed: https://nodejs.org/en/download Then install the NodeJS CKAN client using the following command: npm install ckan

1. To get a valid API key.

Use apikey_show() to obtain a valid API key by supplying username and password parameters:

var CKAN = require('ckan')

var client = new CKAN.Client('https://api.undatacatalog.org');

var data = {
    'username' : 'demo',
    'password' : 'demo'
};

client.action('apikey_show', data, function (err, data) {
    console.log(data);
});

Save the script “apikey.js” then execute using: node apikey.js

If everything goes well, the web service will return a json object that contains your API key: { result: '9c570849-630e-1c6a-9c80-a9fe02f5eb9f', success: true, help: 'http://api.undatacatalog.org/api/3/action/help_show?name=apikey_show' }

2. Verifying the user organization.

In order to verify if demo user is allowed to push for a given organization, we can check the list of users for that organization.

var CKAN = require('ckan')

var client = new CKAN.Client('https://api.undatacatalog.org');

var data = {
    'id' : 'UNDP',
    'include_users' : true
};

client.action('organization_show', data, function (err, data) {
    console.log(data.result.users);
});

If demo user is in the list, that means is allowed to push new datasets into UNDP on demo website:

[ { email_hash: 'b079067c6aa2e4c1f2fa3cabdd788f10dfd03cc3',
    about: null,
    capacity: '',
    name: 'demo',

    created: '2016-01-15T07:36:21-05:00',
    openid: null,
    sysadmin: false,
    activity_streams_email_notifications: false,
    state: 'active',
    number_of_edits: null,
    display_name: 'demo',
    fullname: 'demo',
    id: '4e675d33-5729-407d-be37-d9e9135eeee6',
    number_created_packages: 0 } ]

It is also possible to get a full list of organization for a given permission using organization_list_for_user(). Let's test “package_create” permission on demo website:

var CKAN = require('ckan')

var apikey = '9c570849-630e-1c6a-9c80-a9fe02f5eb9f';

var client = new CKAN.Client('https://api.undatacatalog.org', apikey);

client.action('organization_list_for_user', {'permission' : 'create_dataset'}, function (err, data) {
    console.log(data);
});

Result should be something like the following:

{ result:
   [ 'CEB',
     'CTBTO',
     'CTED',
     'DESA',
     'DPKO',
     …
   ],
  success: true,
  help: 'https://api.undatacatalog.org/api/3/action/help_show?name=organization_list_for_user' }

3. Adding new datasets.

We want to create a new dataset for UNDP. Organization can be specified using “owner_org” field and it can be the organization name or the organization unique identifier.

var CKAN = require('ckan')

var apikey = '9c570849-630e-1c6a-9c80-a9fe02f5eb9f';

var client = new CKAN.Client('https://api.undatacatalog.org', apikey);

var data = {
  'name': 'testing-web-service',
  'title': 'testing the web service',
  'author': 'alice',
  'author_email': 'alice@example.org',
  'maintainer': 'alice',
  'maintainer_email': 'alice@example.org',
  'owner_org': 'UNDP',
};

If it works, the web service will return the full dataset with id / name automatically filled.

4. Removing a dataset.

Now we can try to delete the dataset just created by using id / name that have been returned by the web service. This is done in two steps: 1) we call package_delete() to change publication status, 2) we call da-taset_purge() to remove the dataset completely. Please note that dataset_purge() is not a reversible operation.

var CKAN = require('ckan')

var apikey = '9c570849-630e-1c6a-9c80-a9fe02f5eb9f';

var client = new CKAN.Client('https://api.undatacatalog.org', apikey);

var data = {
  'id': 'testing-web-service',
};


client.action('dataset_purge', data, function (err, data) {
    if (data.result.state == 'inactive') {
            client.action('dataset_purge', data, function (err, data) {
                console.log(data.result.name + ' has been removed !');
            });
    }
});