How to play around with CKAN
In this section, we are going to show some basic functionality of CKAN focused on the API.
Prerequisites
- We assume you've already completed the Getting Started Guide.
- You have a basic understanding of Key data portal concepts:
CKAN is a tool for making data portals to manage and publish datasets. You can read about the key concepts such as Datasets and Organizations in the User Guide – or you can just dive in and play around!
https://docs.ckan.org/en/2.9/user-guide.html
TipInstall a JSON formatter plugin for Chrome or browser of your choice.
If you are familiar with the command line tool curl
, you can use that.
In this tutorial, we will be using curl
, but for most of the commands, you can paste a link in your browser. For POST commands, you can use Postman or Google Chrome Plugin.
First steps
TipBy default the portal is accessible on http://localhost:5000. Let's update your
/etc/hosts
to access it on http://ckan:5000:
vi /etc/hosts # You can use the editor of your choice
# add following
127.0.0.1 ckan
At this point, you should be able to access the portal on http://ckan:5000.
Let's add some fixtures to it. For software, a fixture is something used consistently (in this case, data for you to play around with). Run the following from your terminal (do NOT cut the previous docker process as this one depends on the already launched docker, run in another terminal):
docker-compose -f docker-compose.dev.yml exec ckan-dev ckan seed basic
Optionally you can exec
into a running container using
docker exec -it [name of container] sh
and run the ckan
command there
ckan seed basic
You should be able to see 2 new datasets on home page:
To get more details on ckan commands please visit CKAN Commands Reference.
Check CKAN API
This tutorial focuses on the CKAN API as that is central to development work and requires more guidance. We also invite you to explore the user interface which you can do directly yourself by visiting http://ckan:5000/.
Let's check the portal status
Go to http://ckan:5000/api/3/action/status_show.
You should see something like this:
{
"help": "https://ckan:5000/api/3/action/help_show?name=status_show",
"success": true,
"result": {
"ckan_version": "2.9.x",
"site_url": "https://ckan:5000",
"site_description": "Testing",
"site_title": "CKAN Demo",
"error_emails_to": null,
"locale_default": "en",
"extensions": [
"envvars",
...
"demo"
]
}
}
This means everything is OK: the CKAN portal is up and running, the API is working as expected. In case you see an internal server error, please check the logs in your terminal.
A Few useful API endpoints to start with
CKAN's Action API is a powerful, RPC-style API that exposes all of CKAN's core features to API clients. All of a CKAN website's core functionality (everything you can do with the web interface and more) can be used by external code that calls the CKAN API.
Get a list of all datasets on the portal
http://ckan:5000/api/3/action/package_list
{
"help": "http://ckan:5000/api/3/action/help_show?name=package_list",
"success": true,
"result": ["annakarenina", "warandpeace"]
}
Search for a dataset
http://ckan:5000/api/3/action/package_search?q=russian
{
"help": "http://ckan:5000/api/3/action/help_show?name=package_search",
"success": true,
"result": {
"count": 2,
...
}
}
Get dataset details
http://ckan:5000/api/3/action/package_show?id=annakarenina
{
"help": "http://ckan:5000/api/3/action/help_show?name=package_show",
"success": true,
"result": {
"license_title": "Other (Open)",
...
}
}
Search for a resource
http://ckan:5000/api/3/action/resource_search?query=format:plain%20text
{
"help": "http://ckan:5000/api/3/action/help_show?name=resource_search",
"success": true,
"result": {
"count": 1,
"results": [
{
"mimetype": null,
...
}
]
}
}
Get resource details
http://ckan:5000/api/3/action/resource_show?id=288455e8-c09c-4360-b73a-8b55378c474a
{
"help": "http://ckan:5000/api/3/action/help_show?name=resource_show",
"success": true,
"result": {
"mimetype": null,
...
}
}
Note: These are only a few examples. You can find a full list of API actions in the CKAN API guide.
Create Organizations, Datasets and Resources
There are 4 steps:
- Get an API key;
- Create an organization;
- Create dataset inside an organization (you can't create a dataset without a parent organization);
- And add resources to the dataset.
Get a Sysadmin Key
To create your first dataset, you need an API key.
You can see sysadmin credentials in the file .env
. By default, they should be
- Username:
ckan_admin
- Password:
test1234
- Navigate to http://ckan:5000/user/login and login.
- Click on your username (
ckan_admin
) in the upright corner. - Scroll down until you see
API Key
on the left side of the screen and copy its value. It should look similar toc7325sd4-7sj3-543a-90df-kfifsdk335
.
Create Organization
You can create an organization from the browser easily, but let's use CKAN API to do so.
curl -X POST http://ckan:5000/api/3/action/organization_create -H "Authorization: 9c04a69d-79f4-4b4b-b4e1-f2ac31ed961c" -d '{
"name": "demo-organization",
"title": "Demo Organization",
"description": "This is my awesome organization"
}'
Response:
{
"help": "http://ckan:5000/api/3/action/help_show?name=organization_create",
"success": true,
"result": {"users": [
{
"email_hash":
...
}
]}
}
Create Dataset
Now, we are ready to create our first dataset.
curl -X POST http://ckan:5000/api/3/action/package_create -H "Authorization: 9c04a69d-79f4-4b4b-b4e1-f2ac31ed961c" -d '{
"name": "my-first-dataset",
"title": "My First Dataset",
"description": "This is my first dataset!",
"owner_org": "demo-organization"
}'
Response:
{
"help": "http://ckan:5000/api/3/action/help_show?name=package_create",
"success": true,
"result": {
"license_title": null,
...
}
}
This will create an empty (draft) dataset.
Add a resource to it
curl -X POST http://ckan:5000/api/3/action/resource_create -H "Authorization: 9c04a69d-79f4-4b4b-b4e1-f2ac31ed961c" -d '{
"package_id": "my-first-dataset",
"url": "https://raw.githubusercontent.com/frictionlessdata/test-data/master/files/csv/100kb.csv",
"description": "This is the best resource ever!" ,
"name": "brand-new-resource"
}'
Response:
{
"help": "http://ckan:5000/api/3/action/help_show?name=resource_create",
"success": true,
"result": {
"cache_last_updated": null,
...
}
}
That's it! Now you should be able to see your dataset on the portal at http://ckan:5000/dataset/my-first-dataset.