CKAN provides a RESTful API. If you wish to create a software application that uses the CKAN service, then you will need to know which resources are available, what their locations are, what methods each resource supports, and what the responses might be. All this information is available on this page.
For any action which makes a change to a resource (i.e. all non-GET methods) you will require an API key. To obtain your API key:
A REST interface presents resources at published locations. Here are the names locations of the CKAN REST API resources.
Resourse Name | Location |
---|---|
Package Register | /api/rest/package |
Package Entity | /api/rest/package/PACKAGE-NAME |
Tag Regsiter | /api/rest/tag |
Tag Entity | /api/rest/tag/TAG-NAME |
Each resource location supports a number of methods, which may send or receive a piece of data. Status codes are used to signal the outcome of the operation that is performed in response to the requested method and data.
Here are the methods, data formats, and status codes for the CKAN REST API. Please note 'PUT' operations may instead use the HTTP POST method.
Resource | Method | Request | Response | Statuses |
---|---|---|---|---|
Package Register | GET | Package-List | 200, 301, 500 | |
Package Register | POST | Package | 200, 301, 400, 403, 409, 500 | |
Package Entity | GET | Package | 200, 301, 404, 500 | |
Package Entity | PUT | Package | 200, 301, 400, 403, 404, 500 | |
Tag Register | GET | Tag-List | 200, 301, 500 |
Name | Format |
---|---|
Package-List | [ Name-String, Name-String, Name-String, ... ] |
Package | { name: Name-String, title: String, description: String, url: String, download_url: String, tags: Tag-List } |
Tag-List | [ Name-String, Name-String, Name-String, ... ] |
Tag | { name: Name-String } |
Name-String | An alphanumeric string. |
Code | Name |
---|---|
200 | OK |
301 | Moved Permanently |
400 | Bad Request |
403 | Not Authorized |
404 | Not Found |
409 | Conflict |
500 | Service Error |
All requests that are to result in a change to the CKAN register must be sent with a valid Authorization header.
Header | Value |
---|---|
HTTP_AUTHORIZATION | A valid CKAN REST API authorization token. |
The value passed with this header must satisfy the currently operating requirements of CKAN. The current requirment for a valid Authorization header is the value should be a valid API key.
Header | Example Value |
---|---|
HTTP_AUTHORIZATION | fde34a3c-b716-4c39-8dc4-881ba115c6d4 |
If requests that are required to be authorized are not sent with a currently valid Authorization header, then the requested operation will not be carried out and the CKAN REST API will respond with status code 403.