Quick Start Tutorial

This tutorial quickly introduces the basics of the NSG REST API (NSG-R). 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 NSG-R 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". An application usually refers to the input model or software application that will be run on the HPC resources through NSG. Each request to the NSG-R must identify both the application and the user that is making the request. So the first thing we need to do is register for an account on the NSG-R and tell the NSG-R about the application:

1. Register and log into your NSG-R 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. For this demo, we will be running Jones model from ModelDB. You can register the application as Jonesmodel.
4. Under the Developer menu choose "Documentation" and then "Tools: How to Configure Specific Tools". To run a tool in the NSG-R 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 NEURON on Expanse, which has a tool ID of NEURON_EXPANSE.

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

Submit a Job

For this example job submission, we will use Jones Model from Modeldb (https://senselab.med.yale.edu/modeldb/showModel.cshtml?model=136803). This is how you would submit a job to upload a file named "JonesEtAl2009_r31.zip" from your current directory and run using .

$ curl -u your_username:$PASSWORD -H cipres-appkey:$KEY $URL/job/your_username -F tool=NEURON_EXPANSE  -F input.infile_=@./JonesEtAl2009_r31.zip -F metadata.statusEmail=true

Referring to the command above (and possibly the curl man page), you'll notice that:

• Your 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://nsgr.sdsc.edu:8443/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 .

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 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 your_username:$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://nsgr.sdsc.edu:8443/cipresrest/v1/job/username/NGBW-JOB-NEURON_EXPANSE-nnnn.

Job Results

Once the job is finsished you can list the result files using the URL given by jobstatus.resultsUri.url:

$ curl -u your_username:$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 your_username:$PASSWORD -H cipres-appkey:$KEY -O -J jobfile.downloadUri.url

List Jobs

To get a list of jobs that you've submitted:

$ curl -u your_username:$PASSWORD -H cipres-appkey:$KEY $URL/job/your_username

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 your_username:$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."