Secure EGA Download Client - API Wrapper Class

    4 API Wrapper Class

        4.1 Instantiation

        4.2 Listing, Requesting, Download

        4.3 Decryption

        4.4 Globus Online


4 API Wrapper Class

EGA provides a Java API Wrapper class to make it easy to integrate interaction with this API into Java programs. The functionality of the API is available as functions of this class. In some cases multiple logical API call sequences are combined into class functions It also provides value-added functionality for decrypting data and interaction with the new EGA Globus Transfer API. The class is EgaAPIWrapper and is part of the EgaAPIWrapper.jar package.


4.1 Instantiation

This object is instantiated by providing the REST service URLs to be used. Usually that is just “ega.ebi.ac.uk”.

There is an Information Service URL and a Data Service URL, to allow for the option to use two different URLs. The SSL option should always be set to true.

new EgaDBAPIWrapper(“ega.ebi.ac.uk”, “ega.ebi.ac.uk”, true);

Optionally, the EGA Globus API server and base URL can also be specified (they are default).

new EgaDBAPIWrapper(“ega.ebi.ac.uk”, “ega.ebi.ac.uk”, true, “EGA-globus-server.ebi.ac.uk:8112”, “/ega/rest/globus/v2”);

And there’s also a constructor that logs in to EGA directly:

new EgaDBAPIWrapper(“ega.ebi.ac.uk”, “ega.ebi.ac.uk”, “testuser@ebi.ac.uk”, “testpassword”.toCharArray());

Once the object (EgaDBAPIWrapper apiW = new…) is instantiated, one can log in/out:

apiW.login(“testuser@ebi.ac.uk”, “testpassword”.toCharArray());
apiW.logout();


4.2 Listing, Requesting, Download

Listing information is fairly self-explanatory:

 
String[] ds = apiW.listDatasets();
EgaFile[] fs = apiW.listDatasetFiles(“{dataset stable ID}”);
EgaFile f = apiW.listFileInfo(“{file stable ID}”);
EgaTicket[] ts = apiW.listRequests();
EgaTicket t = apiW.listTicketDetails(“{ticket uuid}”);

Data can then be requested using this function:

String[] ts = apiW.requestByID(“{id}”,“{type}”,“{key}”,“{desc}”);

Where:

{id} = file stable id, or dataset stable id
{type} = “file” or “dataset”
{key} = encryption key for this request (chosen by the user)
{desc} = the label for this request (chosen by the user)

Requests and individual tickets can be deleted:

String[] dr = apiW.delete_request(“{request label}”);
String[] dr = apiW.delete_ticket(“{label}”, “{ticket uuid}”);

Tickets refer to individual requested files, and can be downloaded:

String[] dl = apiW.download_tcp_url“{ticket}”, “{filename}”, “”);

Where:

{ticket} = the ticket uuid to be downloaded
{filename} = the name used to save the downloaded content

And alternative download function is used for optional UDT transfers (can also be used for TCP):

String[] dl = apiW.download_netty”{ticket}”, “{filename}”, “”);

Downloading is an aggregate function that performs several individual steps:

• it creates a file with the given name plus the extension “.egastream”. 
• Then the binary data stream is saved in that file. 
• During the transfer the MD5 of that stream is calculated. 
• Upon (error-free) completion of the transfer the MD5 is compared with the MD5 calculated on the download server. 
• If the checksums match, the “.egastream” extension is dropped to indicate that the download was successful.  If the server can’t be reached for

   MD5 comparison, the “.egastream” remains (download is probably correct). 

• If the checksums are different, the local file is deleted.

There are a few options available for the download:

Boolean v = apiW.setSetPath(“{path}”);
String path = apiW.getPath();

Where {path} is an absolute path to store the downloaded files.

Setting UDT as data transfer choice:

apiW.setUdt({value});
Boolean v = apiW.getUdt();

Where {value} is Boolean true or false.


4.3 Decryption

Downloaded files can be decrypted. A user does not have to be logged in to EGA to decrypt files:

apiW.decrypt(“{key}”,“{dest}”,{List}, 128, {delete}

Where :

 {key} = the encryption key chosen by the user upon request
{dest} = the filename of the decrypted file
{List} = a list of absolute file paths to be decrypted
{delete} = true/false – delete encrypted files after decryption
The path option also works for decryption.

Where {path} is an absolute path to store the downloaded files.


4.4 Globus Online

The Wrapper may also be used to interact with EGA - Globus Online services:

Boolean g = apiW.globusLogin(“{g_user}”,“{g_pas}”.toCharArray());

Where :

{g_user}  = your Globus Online username
{g_pas} = your Globus Online password

This function calls the Globus Online REST API to authenticate the user directly – user credentials are never sent to EGA.

On successful authentication the Globus Online API will return an OAuth 2.0 token which is passed to EGA to act on the user’s behalf for a data transfer. To initiate a Globus Online transfer:

 String id = apiW.globusStartTransfer(“{request}”,”{endpoint}”);

Where:

{request} = a request label
{endpoint} = a GridFTP endpoint where you can authenticate

This function then uses your OAuth token to authenticate you in your endpoint, and set up a subdirectory named with the same name as the request label. Then files are then transferred from the EGA endpoint (“staging”) to your endpoint, in 500GB steps.