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