Overview
This API provides access to ImmPort users who wish to programmatically browse and download the ImmPort shared data. Download is authorized after a user obtains an ImmPort token. The material in this section is primarily to provide background information for working with the File Download Tool.
All API requests require authentication. They must include the authentication token as an Authorization: bearer in the custom HTTP header.
Example for listing a shared data directory or file.
In the following example, an authentication token is saved as an environment variable (token) and passed to the HTTP header in the curl command to download a file.
The following can be run on a terminal at the command prompt.
file_path="/ALLSTUDIES"
token=`curl -k -X POST https://auth.immport.org/auth/token -d username=REPLACE_WITH_USERNAME -d password=REPLACE_WITH_PASSWORD 2>&1 | fgrep '"token"' | sed -e 's/^.*"token" : "//;s/".*$//'`
echo "$token"
curl -k -H "Authorization: bearer $token" -H "Content-Type: application/json" -X POST https://api.immport.org/data/list -d '{"path":"'$file_path'"}'
{"self":{"path":"/ALLSTUDIES","basename":"ALLSTUDIES","type":"directory","size":0,"mtime":"2017-06-15T13:06:37Z","permissions":[{"name":"view"},{"name":"edit"},{"name":"delete"}]},"items":[{"path":"/ALLSTUDIES/ALLSTUDIES-DR22_Metadata","basename":"ALLSTUDIES-DR22_Metadata","type":"directory","size":781381439,"mtime":"2017-06-15T13:06:07Z","permissions":[{"name":"view"},{"name":"edit"},{"name":"delete"}],"fileCount":108},{"path":"/ALLSTUDIES/ALLSTUDIES-DR22_MySQL.zip","basename":"ALLSTUDIES-DR22_MySQL.zip","type":"file","size":355485177,"mtime":"2017-06-26T13:17:35Z","permissions":[{"name":"view"},{"name":"edit"},{"name":"delete"}]},{"path":"/ALLSTUDIES/ALLSTUDIES-DR22_Tab.zip","basename":"ALLSTUDIES-DR22_Tab.zip","type":"file","size":343297398,"mtime":"2017-06-26T13:17:22Z","permissions":[{"name":"view"},{"name":"edit"},{"name":"delete"}]},{"path":**"/ALLSTUDIES/ALLSTUDIES-DR22_table_count.txt"**,"basename":"ALLSTUDIES-DR22_table_count.txt","type":"file","size":2271,"mtime":"2017-06-15T13:01:58Z","permissions":[{"name":"view"},{"name":"edit"},{"name":"delete"}]},{"path":"/ALLSTUDIES/archive","basename":"archive","type":"directory","size":6836959578,"mtime":"2017-06-15T13:01:21Z","permissions":[{"name":"view"},{"name":"edit"},{"name":"delete"}],"fileCount":141}],"item_count":5,"total_count":5,"parameters":{"path":"/ALLSTUDIES","skip":0,"count":100}}
token=curl -k -X POST https://auth.immport.org/auth/token -d username=REPLACE_WITH_USERNAME -d password=REPLACE_WITH_PASSWORD 2>&1 | fgrep '"token"' | sed -e 's/^."token" : "//;s/".$//'`
is a POST to the authentication URLhttps://auth.immport.org/auth/token` with the username and password to get an authentication token.The fgrep command is used search the response for a token and then assign the value of the token to an environment variable named "token".
Once the authentication token is generated, to get a listing of all the files under the file path file_path="/ALLSTUDIES", we use the following line
curl -k -H "Authorization: bearer $token" -H "Content-Type: application/json" -X POST https://api.immport.org/data/list -d '{"path":"'$file_path'"}'
Please check the response tab, it will be listing of all the files under the specified directory. In this case , it is '/ALLSTUDIES' which includes all of the shared data files.
Example of Manual Steps to Download a File
This example approximates the steps that the File Download Tool - downloadImmPortData.sh runs when used to download a file. We highly recommend using downloadImmportData.sh program and not executing these steps manually. This example assumes you have installed the File Download Tool and are running this Shell script in the bin directory of that distribution. In addition, you will need to create a output directory at the same level as the bin directory.
When the shell script runs successfully the log files generated by Aspera and the file you have requested to download will be located in the output directory.
#!/bin/bash
file_path="/SDY1/StudyFiles/Casale_Study_Summary_Report.doc"
# Obtain ImmPort Token
export token=`curl -X POST https://auth.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1 | fgrep '"token"' | sed -e 's/^.*"token" : "//;s/".*$//'`
echo "$token"
# Obtain Aspera Token
export aspera_token=`curl -H "Authorization: bearer $token" -H "Content-Type: application/json" -X POST https://api.immport.org/data/download/token --data '{ "paths" : [ "SDY1/StudyFiles/Casale_Study_Summary_Report.doc" ] }' 2>/dev/null | sed -e 's/^.*\"token\" *: *\"//;s/\".*$//'`
echo "$aspera_token"
# Download File using Aspera
ASPERA_BIN_DIR="../aspera/cli/bin"
ASPERA_PRIVATE_KEY_FILE="../aspera/cli/etc/asperaweb_id_dsa.openssh"
ASPERA_USERNAME="databrowser"
ASPERA_SERVER="aspera-immport.niaid.nih.gov"
../aspera/cli/bin/linux/ascp -v -L ../output -i ${ASPERA_PRIVATE_KEY_FILE} -O 33001 -P 33001 -W ${aspera_token} --user="${ASPERA_USERNAME}" ${ASPERA_SERVER}:'/SDY1/StudyFiles/Casale_Study_Summary_Report.doc' ../output