API interaction

The API can be used via command-line tools or within scripts. Only datasets with the standard Datacite format can be managed via API.

Authentication

Unless a dataset is public, you will need an API token to be able to interact with it. In order to create one, you need to login into the WebUI of MetaStore and go to your account. Please follow these instructions before proceeding.

CKAN Actions

Irrespective of the tool you are going to use, you will need to use CKAN actions to achieve what you want to do. Some examples are package_create, package_show,resource_update. Look at the official documentation for more information.

Note

For legacy reasons, datasets are still called packages in the action names.

Datacite Metadata fields

Label	Name	Comment
Title	`title`	MetaStore will attribute the value of the field `name` when no title is given.
Name	`name`	URL-friendly, required by the API
UUID	`id`	Generated by MetaStore when not given
Type	`type`	Must be `standard` for the standard Datacite Format
Creators	`creators`
Organization	`owner_org`	MetaStore organization, required by the API
Publisher	`publisher`
Publication Year	`publicationyear`
Resource Type	`resourcetype`
Subject	`subject`
Contributor	`contributor`
Date	`date`
Language	`language`
Alternate Identifier	`alternateidentifier`
Related Identifier	`relatedidentifier`
Size	`size`
Format	`format`
Version	`version`
Description	`description`
Geolocation	`geolocation`
Funding Reference	`fundingreference`
Related Item	`relateditem`
Licence	`rightslist`

Tools

ckanapi

ckanapi is a command line interface and Python module for accessing the CKAN Action API.

Datasets Listing

ckanapi action package_list -r https://metastore.mpcdf.mpg.de --insecure

Dataset Creation

ckanapi action package_create -r https://metastore.mpcdf.mpg.de name=<DATASET-NAME> owner_org=mpcdf type=standard -a <API-KEY>

curl

Dataset Creation

curl -XPOST -H "Authorization: <API-KEY>" https://metastore.mpcdf.mpg.de/api/3/action/package_create -d '{"name":"final-experiment", "title":"Final Experiment", "creators":"Nicolas Fabas, Thomas Zastrow", "type":"standard", "owner_org":"mpcdf", "publicationyear":"2023", "version":"4.2", "description":"This is our final experiment", "subject": "waves, particles"}'

Resource Creation

curl -XPOST -H "Authorization: <API-KEY>" https://metastore.mpcdf.mpg.de/api/3/action/resource_create -d '{"package_id":"570111cc-66df-4946-b291-5cb99dbd8045", "name":"resource.tar.gz", "format":"tar.gz", "url":"https://objectstore.hpccloud.mpcdf.mpg.de/testbucket/resource.tar.gz"}'

HTTPie and the CKAN Requestor

HTTPie is another HTTP client which is easier to use than curl. The CKAN Requestor is an MPCDF tool based on HTTPie. Its purpose is to automatically construct an HTTPie query.

https -p hbHBm  --verify=no ://metastore.mpcdf.mpg.de/api/3/action/package_create Authorization:<API-KEY> name=final-experiment title="Final Experiment" creators="Nicolas Fabas, Thomas Zastrow" type=standard owner_org=mpcdf publicationyear=2023 version=4.2 description="This is our final experiment" subject="waves, particles"

With the CKAN Requestor:

./requestor.sh name=final-experiment title="Final Experiment" creators="Nicolas Fabas, Thomas Zastrow" type=standard owner_org=mpcdf publicationyear=2023 version=4.2 description="This is our final experiment" subject="waves, particles"

If you already created a metadata file with the MMD tools, you can simply use it with the CKAN Requestor to publish the dataset like so:

./requestor.sh < metadata.mmd