REST API - Index

REST API

Introduction

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.

API Keys

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:

  1. Login as a normal user.
  2. Visit the API Key page.

Resources and Locations

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

Methods, Data Formats, Status Codes

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

Data Formats

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.
To send request data, create a simple data structure, then convert it to a JSON string, then percent-encode the JSON string, then send it as the request body. Response data will be in the response body.

Status Codes

Code Name
200 OK
301 Moved Permanently
400 Bad Request
403 Not Authorized
404 Not Found
409 Conflict
500 Service Error

Authorized Requests

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.

Example Client Implementations