Using CKAN's API
Users can utilize the Data Catalogue's API endpoints on dataset pages by clicking the green Data API button in the image below.
Doing so provides you with various endpoints that you can utilize:
The full documentation about the CKAN API can be found on the ckan.org website. You can make use of the APIs provided by the CKAN software to access the catalogue of datasets on CanWIN. The API provides both RESTful and functional interfaces, all in JSON format, making it suitable for a wide range of users.
For example, through this API service users can:
- get JSON-formatted lists of datasets;
- get a full JSON representation of a dataset or resource;
- search for datasets or resources matching a query;
- get an activity stream of recently changed datasets
In CanWIN we have created additional searchable terms you can use to access information, as listed below. There may be some differences in the original CKAN terms (these are the terms you will see currently on the CanWIN site) and the terms used for searching the API. These are highlighted in the table below. For example, you will see the term 'keyword' on the CanWIN site, but to search for keywords via the API, the search term would be 'tag', and not 'keywords'.
| Data Catalogue Term | CKAN Search Term | Search Example |
|---|---|---|
| Keyword | Tag | https://lwbin-dev.ad.umanitoba.ca/data/api/3/action/tag_list |
| Dataset | Package | https://lwbin-dev.ad.umanitoba.ca/data/api/3/action/package_list |
| Facility | Organization | https://lwbin-dev.ad.umanitoba.ca/data/api/3/action/organization_list |
| Theme | Group |
https://canwin-datahub.ad.umanitoba.ca/data/api/3/action/group_list |
Making an API request
To call the API, you can post a JSON dictionary in an HTTP POST request to one of the URLs. The parameters for the API function should be given in the JSON dictionary. CanWIN will also return its response in a JSON dictionary.
There are several methods of making an HTTP POST request by using software tools, REST clients or web services.
HTTPie
One way to post a JSON dictionary to an URL is using the command-line HTTP client HTTPie. In order to use HTTPie as the command line client, Windows users must also install the package manager chocolatey It is recommended users specify the version of the CKAN API they are using. The latest version is version 3. Users can find the API version used in the instance of CKAN they want to access by typing the following URL into their browser:
After installing HTTPie, you can access the different CKAN Action API endpoints using different action functions. For example, to get a list of the names of all the themes within the CanWIN data catalogue, call the organization_list action function by running this command at command line:
The colour-coded JSON response will look like this:
This response is composed of a JSON dictionary with three keys:
1. "help": the documentation string for the function you called, or the URL endpoint called.
2. "result": this is the returned result from the function you called. The type and value of the result depend on which function you called. For example, in the case of the group_list function it's a list of strings, which are the names of all the themes in CanWIN. If there was an error responding to your request, the dictionary will contain an "error" key with details of the error instead of the "result" key. A response dictionary containing an error will look like this:
The API aims to always return "200 OK" as the status code of its HTTP response, whether there were errors with the request or not, so it's important to always check the value of the "success" key in the response dictionary and (if success is false) check the value of the "error" key.
Note: If there are major formatting problems with a request to the API, CanWIN may still return an HTTP response with a 409, 400 or 500 status code (in increasing order of severity).
cURL
Similarly to HTTPie, a HTTP POST request can be made to the CKAN API using cURL at a command line interface:
This gives the same result as HTTPie, however, the JSON output is not colour-coded or structured for easy reading.
Authentication and API tokens
Certain API functions such as package_create (creates a new dataset) require authorization and a CanWIN user account. When calling an API function that requires authorization, you must authenticate yourself by providing an authentication key with your HTTP request. For our version of CKAN, the recommended mechanism to use are API tokens. These are encrypted keys that can be generated manually from the user interface by clicking on the system icon next to the dashboard icon on the top right menu. At the bottom, you will see the Regenerate API Key orange button. Click to generate a new API key.
To conduct the same request above with authorization, include "Authorization: XX", where XX is the users' Private API Key. In the following example, we are using curl to access the data.