Attention!

Beginning on 1st of October 2016, we are going to disable the support for standard HTTP.
The webservice and especially our API will only be accessible via HTTPS. Please make sure to change your scripts until this date.

GeneTrail2 RESTful API

GeneTrail2 is fully scriptable via a
RESTfulAPI.
This allows our users to easily process larger enrichment studies in an automated fashion or to integrate
GeneTrail2 into existing tools.
As the API solely relies on standard HTTP requests no special libraries or software is required and bindings
for any programming language can be created. In the following we will introduce the basic concepts needed
for working with the API. If you are looking for the documentation of all implemented methods see our
API reference.

Introduction

RESTful API represent resources as
URLs on the server. Actions on the
URLs are usually conducted using the standard
HTTP verbsGET, POST, PUT, and DELETE. For example GeneTrail2
is focused on the concept of Sessions, Jobs, and Resources. Sessions
are a collection of Resources such as score lists, expression matrices, categories, etc. They are usually
produced by executing a Job. For obtaining a new Session object in GeneTrail2 we can use the following
request:

GET /api/session

This might create the following JSON formatted output:

{ "session": "116654b3-7b2e-489b-ab66-2a377b9928c7" }

Using this session identifier we can now upload files, start computations, and display results. If a session is
no longer needed we can delete it and all its contents by issuing the request

DELETE /api/session/116654b3-7b2e-489b-ab66-2a377b9928c7

For displaying a resource we can use the following request:

GET /api/resource/988?session=b0e9a4aa-345d-45f1-bc37-0e059ccd907c

Here session=b0e9a4aa-345d-45f1-bc37-0e059ccd907c specifies the session from which the
resource should be retrieved and 988 is the identifier of the Resource object. The generated
response looks like this:

Example

So how does a script using the GeneTrail2 API in practice?
Suppose you want to compute multiple enrichments from a matrix of gene expression values. For accomplishing this
we will write a Python script. We start with the main procedure that calls some helper functions that do the
actual work.

importjson# Load method definitionsfromgravitonimport*# Load assignment of samples into groupsfromdataGroupsimport*# Obtain a sessionkey=getSession()# Upload the input data to the servermatrixId=uploadFile(key,'matrix.txt')['id']# Compute scores for the input data and the# data groups using the shrinkage-t-test# The first call will only create the job object# on the server, but will not yet compute anything.setupScoring(key,'independent-shrinkage-t-test',file1=matrixId,sg=json.dumps(groups['sg']),rg=json.dumps(groups['rg']))# Run the actual computationscores=runJob(key)['scores']['id'];# Create a list of categories for which we# want to compute our enrichmentscategories=['9606-gene-go-biologicalprocess','9606-gene-kegg-pathways','9606-gene-reactome-pathways','9606-gene-pfam-proteinfamilies',]# Create and run the job for the enrichment.# We use the GSEA algorithm here.setupEnrichment(key,'gsea',scores,categories)result=runJob(key)['enrichment']['id']# Download and store the resultsdownloadResult(key,result,'mrnaAllSamples.gsea.zip')

You can download the example input file here.
The dataGroups.py script can be downloaded here.

The methods getSession, uploadFile, setupScoring,
setupEnrichment, runJob, and downloadResult are defined in the graviton module that is available from Github.
You can install it via pip install git+git://github.com/dstoeckel/Graviton.py.git.

Bindings

In order to facilitate using GeneTrail2 from other languages, we created a set of bindings.
Currently, bindings are available for: