File Upload API

ERROR

JavaScript must be enabled.

A REST based API is available for data providers who wish to script interactions to manage their dataset files.

Prerequisites

You must be a data provider that has been granted permissions to write to a dataset.

Authentication

The API supports API Tokens over SSL.

Your API Token can be sent via an HTTP Header or an HTTP Query Parameter. In both cases the header name or query parameter is named 'api-token'.

HTTP Methods

The API supports the following HTTP methods: POST, PUT, and DELETE.

At this time, the POST and PUT methods perform the same exact behavior.

Upload File to a Dataset

Below is an example curl command to upload a file into a dataset with the short name "CPL_MAR".

In this example your API Token is sent via an HTTP Header Attribute.

$ curl -v --header "authorization: api-token <api-token>" -X POST -F file=@"./<file_to_upload.ext>" https://<host-name>/api/v1/dataset/<dataset-short-name>/file.json

To send your API Token via an HTTP Query Parameter at the end of the url.

$ curl -v -X POST -F file=@"./<file_to_upload.ext>" https://<host-name>/api/v1/<dataset-short-name>/file.json?api-token=<api-token>

If you were to upload a local file named "readme.txt" to your dataset with an api-token of 1234567890.

$ curl -v --header "authorization: api-token 1234567890" -X POST -F file=@"./readme.txt" https://www.earthsystemgrid.org/api/v1/dataset/ncl.630.0/file.json

A successful upload will show "201 Created" in the response: HTTP/1.1 201 Created

Delete File from a Dataset

You may delete a file via this interface, for example, if you wanted to delete the readme.txt file.

$ curl -v --header "authorization: api-token <api-token>" -X DELETE https://<host-name>/api/v1/dataset/<dataset-short-name>/file/<target-filename.ext>

Information

Dealing with published datasets and pre-published dataset versions can be confusing.

When using the above dataset based API urls, the file will be uploaded or deleted to the latest published version of that dataset. If there are no published versions of that dataset, the files will be uploaded to the pre-published version of that dataset.

To use a new pre-published version of a dataset previously published, the dataset version based API urls must be used.

Information

When a new version of a dataset is created all the files from the previous version are copied into the new version.

Upload File to a Dataset Version

Files can be managed for a specific dataset version. The dataset version is identified by its dataset short name plus the dataset version identifier.

Below is an example curl command to upload a file into a specific dataset version.

$ curl -v --header "authorization: api-token <api-token>" -X POST -F file=@"./<file_to_upload.ext>" https://<host-name>/api/v1/dataset/<dataset-short-name>/version/<dataset-version-identifier>/file.json

If you were to upload a local file named "readme.txt" to your dataset version "2.0" with an api-token of 1234567890.

$ curl -v --header "authorization: api-token 1234567890" -X POST -F file=@"./readme.txt" https://www.earthsystemgrid.org/api/v1/dataset/ncl.630.0/version/2.0/file.json

A successful upload will show "201 Created" in the response: HTTP/1.1 201 Created

Delete File from a Dataset Version

To delete a file from a specific Dataset Version via this API.

$ curl -v --header "authorization: api-token <api-token>" -X DELETE https://<host-name>/api/v1/dataset/<dataset-short-name>/version/<dataset-version-identifier>/file/<target-filename.ext>

Debugging

You will get a pile of other logging if using the curl verbose flag "-v".