Climate Data Gateway
at NCAR

File Upload API


ERROR
Cookies must be enabled.

This REST API is for data providers who wish to script interactions to manage dataset files.

Structure of File Upload API Rest URLs

https://<host-name>/api/v1/dataset/<dataset-short-name>/file/<file-name>.<extension>

The <dataset-short-name> can be found from the dataset HTML URL. For example, the dataset found at the URL below has a short name of "ncl.630.0":

https://www.earthsystemgrid.org/dataset/ncl.630.0.html

Pre Requisites

You must have a dataset to upload files to as well as a user account with permissions to write to the dataset.

Authentication

The API supports API Tokens over SSL.

Methods

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

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

To replace a file, you must first DELETE it, then PUT it back.

Put Examples

Below is an example curl command to push a file into a dataset with short name "CPL_MAR". You will need to substitute your username and password and identify the file you are working with.

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

-or with a query parameter-

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


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

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

-or with a query parameter-

curl -v -X PUT -F file=@"./readme.txt" https://www.earthsystemgrid.org/api/v1/dataset/ncl.630.0/file/readme.txt?api-token=1234567890
        

For files that have spaces in their names, you will have to percent encode the spaces by hand:

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

-or with a query parameter-

curl -v -X PUT -F file=@"./readme.txt" https://www.earthsystemgrid.org/api/v1/dataset/ncl.630.0/file/file%20with%20spaces.txt?api-token=1234567890
        


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

Post Example

$ 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/<target-filename.ext>

-or with a query parameter-

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

Delete Example

You can also 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>

-or with a query parameter-

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

Debugging

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

Document based on Gateway version: 2.0.96