Quick Start Tutorial

This tutorial quickly introduces the basics of the CIPRES REST API (aka, the CRA). It shows how to access the API with the standard unix "curl" command from Unix, Linux or a MacOS terminal window. Please refer to the User Guide for a more in-depth explanation and description of the many options that are available.

If you aren't familiar with curl, google "curl" or run "man curl".

Preliminaries

All access to the CRA happens through an "application". We won't be writing an application in this tutorial, instead, we'll view the curl commands we issue as our "application". Each request to the CRA must identify both the application that is making the request and the user that it's made on behalf of. So the first thing we need to do is register for an account on the CRA and tell the CRA about our application:

  1. Register and log into your CRA account.
  2. From the Developer drop down menu choose "Application Management" and press the "Create New Application" button.
  3. Complete the form:
    • Choose the default DIRECT Authentication Type
    • Make a note of the Application ID that is assigned.
  4. Under the Developer menu choose "Documentation" and then "Tools: How to Configure Specific Tools". To run a tool in the CRA you need to know its tool ID. The tool IDs are shown in bold on the "Tools: ..." page. In this tutorial we'll be running RAxML version 8, which has a tool ID of RAXMLHPC8_REST_XSEDE.

The examples in this tutorial assume you've set the following environment variables:
$ export URL=https://cipresrest.sdsc.edu/cipresrest/v1
$ export CRA_USER=your_cra_username
$ export PASSWORD=your_cra_password
$ export KEY=your_application_ID

Submit a Job

This is how you would submit a job to upload a file named "raxml_inputphy.txt" from your current directory and run RAxML on it. You can download an example relaxed phylip format file to use as input if you don't have one handy. 
    $ curl -u $CRA_USER:$PASSWORD -H cipres-appkey:$KEY $URL/job/$CRA_USER -F tool=RAXMLHPC8_REST_XSEDE  -F input.infile_=@./raxml_inputphy.txt -F metadata.statusEmail=true
Referring to the command above (and possibly the curl man page), you'll notice that:
  • Your CRA username and password are sent in basic authentication headers.
  • The application ID is sent in a custom http header named "cipres-appkey".
  • The job submission url is of the form https://cipresrest.sdsc.edu/cipresrest/v1/job/username.
  • A job submission always has at least 2 form fields, "tool" and "input.infile_".
  • "metadata.statusEmail" is an optional field that enables job completion email.

Each tool has additional tool specific fields that can be used to configure a run. Use the interactive Tool Configuration Helper to get familiar with a tool's fields (also called parameters). The parameters are documented on the tool's "REST Tool Info" page in Tools: How to Configure Specific Tools.

Job Status

Successful job submission returns an XML jobstatus object. One of the fields in the jobstatus object, jobstatus.selfUri.url, gives the job's url. You can use this url to to poll for updated status and find out when the job has finished (if you didn't set metadata.statusEmail=true). You'll know the job is finished when jobstatus.terminalStage = true. 
    $ curl -u $CRA_USER:$PASSWORD -H cipres-appkey:$KEY jobstatus.selfUri.url

Be sure to substitute the actual value of jobstatus.selfUri.url from the returned XML jobstatus object when you run this command. It will look something like https://cipresrest.sdsc.edu/cipresrest/v1/job/username/NGBW-JOB-RAMLHPC8_REST_XSEDE-nnnn.

Job Results

Once the job is finsished you can list the result files using the URL given by jobstatus.resultsUri.url: 
    $ curl -u $CRA_USER:$PASSWORD -H cipres-appkey:$KEY jobstatus.resultsUri.url
This returns an XML results object which contains a sequence of "jobfile" objects. Each jobfile has a URL given by jobfile.downloadUri.url that can be used to download the file: 
    $ curl -u $CRA_USER:$PASSWORD -H cipres-appkey:$KEY -O -J jobfile.downloadUri.url

List Jobs

To get a list of jobs that you've submitted: 
    $ curl -u $CRA_USER:$PASSWORD -H cipres-appkey:$KEY $URL/job/$CRA_USER
This returns a sequence of abbreviated jobstatus objects. Use the jobstatus.selfUri.url member of any of the abbreviated jobstatuses to retrieve the full jobstatus.

Delete and/or Cancel a Job

Please delete your jobs after you've downloaded the results. If you delete a job that hasn't completed yet, it will be cancelled and then deleted. 
    $ curl -u $CRA_USER:$PASSWORD -H cipres-appkey:$KEY -X DELETE jobstatus.selfUri.url
Nothing is returned from a successful DELETE operation. You can verify that the job was deleted by trying to delete it again or by trying to get its status. A 404 NOT FOUND status should be returned along with an XML error object with displayMessage = "Job Not Found."