RESTful Access to Analysis Tool Manager (version beta 4.0)

Introduction

Part of the functionality that we are including in the GenomeSpace CDK is a Java API that provides client applications access to authentication, authorization, data file services, and Analysis Tool Manager services.  If your application is not written in Java and you want to add GenomeSpace support to it, you can still access these services by contacting them directly.

HTTP Client Requirements

In addition to supporting the usual HTTP POST, GET, PUT, etc., your client will have to be able to do the following:

Handle cookies

Accept cookies and send their values to the correct domains.

Support HTTP redirects

Accept as a response HTTP code 303 and automatically GET the response from the specified location URL.

Support Basic Authentication

Client should be ready to respond to Basic authentication credentials challenge via HTTP response code 401.

Support JSON marshalling and unmarshalling

The Analysis Tool Manager will generate responses using JSON.

Support for HTTPS

All communications to the Identity Server and the Analysis Tool Manager service occur through secure HTTP.  We have obtained third-party certificates for our servers, so updating trust stores should not be necessary in most cases.

Common Request Headers

Every request to the Analysis Tool Manager should include the Accept header with a preference for the media types application/json and application/text.  The gs-token cookie should also be included.  More on gs-token below.

In general it is desirable (but optional) for tools to add a header (or request parameter, or cookie, any of these forms can be used) gs-toolname=MyToolName to all their requests.  This is optional but identifies which tool is making a request which permits more detailed usage reporting within the GenomeSpace system.

Login and Authentication

You can do an explicit login at the beginning of a session by issuing a GET to: https://identity.genomespace.org/identityServer/basic. You will get an HTTP 401 response code with a request for credentials using Basic Authentication.  Basic authentication is described in RFC2617.  If you are utilizing an HTTP library, it is very likely that it already includes support for Basic authentication. On successful submission of credentials, the server’s response will include a cookie named gs-token. The cookie should be included in all subsequent requests to the Analysis Tool Manager. If your library has cookie handling enabled, the inclusion of the cookie in requests should happen automatically. If an Analysis Tool Manager request does not include the gs-token cookie or the session has expired, server will respond with another 401 authentication challenge. If successfully responded to, the client will be redirected to the original request.

WADL

All the operations available from the Analysis Tool Manager are described in Web Application Description Language (WADL) specification show below:

<application>
  <doc jersey:generatedBy="Jersey: 1.5 01/14/2011 12:36 PM"/>
  <resources base="https://dmdev.genomespace.org:8444/atm/">
    <resource path="v{1.0}/webtool">
      <resource path="descriptor">
        <method id="getWebTools" name="GET">
          <response> 
            <representation mediaType="application/json"/>
          </response>
        </method>
      </resource>
      <resource path="{internalIdOrName}/descriptor">
        <param name="internalIdOrName" style="template" type="xs:string"/>
        <method id="getWebToolDescriptor" name="GET">
          <response>
            <representation mediaType="application/json"/>
          </response>
        </method>
      </resource>
      <resource path="{toolName}/launchurl">
        <param name="toolName" style="template" type="xs:string"/>
          <method id="getWebTool" name="GET">
            <response>
              <representation mediaType="text/plain"/>
            </response>
          </method>
      </resource>
    </resource>
  </resources>
</application> 

WebToolDescriptor Object

Information about Web Tools available from the Analysis Tool Manager will be returned in JSON objects.  The WebToolDescriptor object describes a Web Tool.  An example of a WebTool is GenePattern.  The fields in a WebToolDescriptor are shown below:

FileParameter

Defines a FileParameter that will placed on the URL for a WebTool, specifying that the tool should download that file (or files) from GenomeSpace.

GSDataFormats describe the data sources.  The fields are shown below:

Example ToolDescriptor objects are included in the Appendix.

Accessing WebTools

List of WebTools

You can retrieve a list of WebToolDescriptors by sending a get request as shown below.  All URLs are preceded by https://atm.genomespace.org/atm/v1.0.

This will return a collection of WebTools in JSON format.

WebTool ByName

You can retrieve the descriptor for a webtool by name using a get request as shown below. 

where webtoolname is the name of a WebToolDescriptor.  This will a return a WebTool descriptor in JSON format, or 404 there is no webtool with the given name.

WebTool Launch URL

You can retrieve an URL to launch a particular web tool, passing in the paths of files in GenomeSpace as arguments for the WebTool.  The format of the URL is as follows:

where webtoolname is the name of a WebToolDescriptor object, fileparamname1 is the name of a FileParameter understood by the given WebTool, gs_path_to_file1 is the GenomeSpace path to a file that has been uploaded to GenomeSpace.  Note that the file path names must be URL encoded.  If the WebTool takes multiple arguments as input, the arguments must be separated by ampersands.
Note that some WebTools (e.g., IGV) take multiple filenames for a single parameter.  For these tools, the FileParameter is defined with the compositeFilename being true, and the URL sent to the ATM would be of the form:

 webtool/webtoolname/launchurl?fileparamname1=gs_path_to_file1<delimeter>gs_path_file2

This method will return a text response with the URL in the body of the response.

Appendix: Sample ToolDescriptors

A simple WebToolDescriptor with no parameters:

{"tags":[],
"internalId":"6c09bfe1-6dd4-4c97-a13f-8ef72147b6a7",
"author":"UCSD","name":"Cytoscape",
"description":"Cytoscape An open source platform for complex-network analysis and visualization",
"baseUrl":"http:\/\/chianti.ucsd.edu\/genomespace\/cytoscape.jnlp",
"fileParameters":[]} 

A WebToolDescriptor with a parameter:

{"tags":[],
"internalId":"4b959bde-864a-46d8-a23f-0dc57245113f",
"author":"Jim Robinson",
"name":"IGV",
"description":"Integrative Genomics Visualizer",
"baseUrl":"http:\/\/www.broadinstitute.org\/igv\/projects\/dev\/igv_gs.jnlp",
"fileParameters":[
  {"formats":[
    {"name":"gct",
     "description":"A tab-delimited text file containing gene expression data.  Used by GenePattern.",
     "url":"http:\/\/www.genomespace.org\/datamanager\/dataformat\/gct",
     "fileExtension":"gct"},
    {"name":"bed",
     "description":"BED format provides a flexible way to define the data lines that are displayed in an annotation track.",
     "url":"http:\/\/www.genomespace.org\/datamanager\/dataformat\/bed",
     "fileExtension":"bed"},
    {"name":"res",
     "description":"The RES file format is a tab delimited file format that describes an expression dataset.",
     "url":"http:\/\/www.genomespace.org\/datamanager\/dataformat\/res",
     "fileExtension":"res"}],
  "compositeFilename":true,
  "nameDelimiters":",",
  "name":"sessionURL",
  "required":false,
  "internalId":"45517701-1c6a-4a6a-8fb2-305bdb8a8ef1",
  "parentInternalId":"4b959bde-864a-46d8-a23f-0dc57245113f"}]
}