Directly with the CanWIN API

CKAN API

CanWIN Datahub site was developed in partnership with CKAN open source data management system. Through this platform, users can utilize the CKAN API. Further explanation and documentation can be found on the ckan.org website; however, below on this page we will summarize API services users can make use of 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 clients.

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 you can utilize additional searchable terms, which have changed from the original CKAN phrasing. These terms are listed below, where the CKAN API searchable term should be used to access the information as described.

CanWIN Term CKAN Search term Browser 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

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.

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. The request also provides the version of CKAN and a list of extensions implemented. 

For example, to get a list of the names of all the organizations within the CanWIN datahub, install HTTPie and then call the organization_list API function by running this command in a terminal:

 

Note: In CanWIN "tag" is the same as "keyword", "theme" is the same as "group" and "organization" is the same as "facility" so the original CKAN labels must be used for the call (tag, group, organization). The JSON response will look like this:

This response is composed of a JSON dictionary with three keys:

1. "help": the dcoumentation string for the function you called. This links to documentation about the API call and will provide further information where required.

2. "result": this is the resturned result from the funciton 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:

3. "success": true or false 

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 respone with a 409, 400 or 500 status code (in increasing order of severity).

Authentication and API tokens

By default CanWIN users can only access read-only API functions to get data out of the system and view it. 

Certain advanced API functions require authorization and a CanWIN user account. The API then uses the same authorization functions and configuration as the web interface, so if a user is authorized to do something in the web interface they will be authorized to do it via the API as well.

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. 

Image showing orange button for users to click the Regenerate API Key button

To provide your API token in an HTTP request, include it in an Authorization  line placed before your request.

For example, to conduct the same request above but including the "Authorization" line, type in the following line, where XX is the users' Private API Key.  In this example, we are using the command line tool curl to access the data. 

Note: API functions listed below are available to all users and cover read-only operations.

REST API

The API functions can also be called via an HTTP GET request typed directly into a web browser. For example, to get a list of datasets (called packages by the API), type the URL below in your browser:

To search for datasets(packages) by keyword for example, "Freshwaters", type the URL below into your browser:

Note: Browser plugins like JSONView will format and colour your JSON response nicely in your browser

Example HTTP query for water using Chrome webbrowser and JSONView plugin
Example query using REST API in web browser and water as query parameter.

The search query is given as a URL parameter "?q=Freshwaters". Multiple URL parameters can be appended, separated by & characters. For example, to get only the first 10 matching datasets for the query using the keyword "Freshwaters" use the following URL: