GenePattern REST API


GenePattern provides a variety of RESTful web services for programmers looking to integrate GenePattern into a web application. A specification of these services is also available in the form of a Web Application Description Language (WADL) file. This file can be accessed for a particular GenePattern server by using the URL format shown below.

http://your_server:your_port/gp/rest/application.wadl

A link to the WADL file on the GenePatten public server is available here. Note that clicking this link will prompt you for your GenePattern authentication credentials on the public server.

For more information on using GenePattern programmatically, see the Programmer's Guide.

Authentication

Most resources that are part of the GenePattern REST API require authentication before they can be accessed. Several forms of authentication are accepted and are described below.

Basic Authentication

Basic Authentication requires that an Authorization header is added to each request sent to the REST API. The value of this header should include the word Basic, a space and then a string consisting of the user's GenePattern username:password encoded Base64, compliant with the RFC2045-MIME specification.

For example, if the GenePattern username is Aladdin and the password is OpenSesame, then the authorization header will be as follows:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

For more information on Basic Authentication see the full specification (RFC2617).

GenePattern OAuth2

The GenePattern REST API provides OAuth2 endpoints that allow clients to authenticate with GenePattern. Unlike most resources, the OAuth2 endpoints are intended to be accessed before authentication.

For a complete description of GenePattern's OAuth2 service, see the OAuth2 resource below.

For more information on OAuth2 in general, see the OAuth2 specification.

GenomeSpace Single Sign-On

As part of the GenomeSpace initiative, GenePattern supports single sign-on using GenomeSpace credentials. Before these credentials are valid in GenePattern, however, a user must first associate their GenomeSpace account with their GenePattern account. This can be achieved by clicking on the GenomeSpace icon on the login page in the GenePattern web interface, then following the resulting prompts.

Once a user's GenePattern account and GenomeSpace accounts have been associated, using GenomeSpace credentials with the GenePattern REST API can be accomplished in one of two ways:

GenomeSpace Basic Authentication

A user's GenomeSpace username and password can be passed to GenePattern for verification using Basic Authentication. This uses the exact same process described in Basic Authentication above, only the user's GenomeSpace username and password are included instead of their GenePattern username and password.

For more information on Basic Authentication see the full specification (RFC2617).

GenomeSpace Username and Token

When authenticating with the GenomeSpace RESTful API, a security token is issued. This security token, along with the associated GenomeSpace username, can be used to access the GenePattern REST API. To do this, both pieces of information must be included as headers on each request made to GenePattern's RESTful web services. The appropriate form of each header is shown below, assuming the username Aladdin and a fictional token.

gs-username: Aladdin

gs-token: ZbxhZGRpbjpPcGVuU2VzYwer=

For more information see the GenomeSpace API documentation.

Resources

The GenePattern REST API provides a variety of resources that can be used when calling GenePattern from a web application. Each resource provides a number of endpoints for invoking GenePattern functionality. These resources are described in detail below.

Tasks

Content coming soon

Jobs

Content coming soon

Upload

Content coming soon

Data

Content coming soon

GenomeSpace

Content coming soon

/gp/rest/v1/genomespace/createDirectory

  • Method: PUT
  • Accepts:
  • Returns:

Content coming soon

/gp/rest/v1/genomespace/delete

  • Method: DELETE
  • Accepts:
  • Returns:

Content coming soon

/gp/rest/v1/genomespace/refresh

  • Method: PUT
  • Accepts:
  • Returns:

Content coming soon

/gp/rest/v1/genomespace/save

  • Method: POST
  • Accepts:
  • Returns: text/plain

Content coming soon

/gp/rest/v1/genomespace/tool

  • Method: GET
  • Accepts:
  • Returns:

Content coming soon

Tags

The tags resource allows a client to interact with tags in GenePattern. There are two seperate groups of tags covered: job tags and module tags. These are seperate groups of tags and should not be confused when developing using the associated endpoints.

  • Job Tags: Are attached to a job when it is launched, or attached to a job afterward using the GenePattern web application.
  • Module Tags: Currently the only tag that can be directly applied to modules is pinning the module among a user's favorites. In the user interface, often a module's categories or associated suites will be used in a tag-like way as well.

/gp/rest/v1/tags

  • Method: GET
  • Accepts:
  • Returns: application/json

This endpoint returns a list of all job tags for the user. Only tags the user has used to tag jobs will appear in the list. Each tag in the list is returned in the following JSON format:

{
    "value": "Tag String"
}

/gp/rest/v1/tags/pin

  • Method: POST
  • Accepts: application/json
  • Returns:

This endpoint is used to pin a module to a user's favorites. It consumes a JSON input in the following format:

{
    "user": "The user's username",
    "lsid": "This is the LSID of the module being pinned",
    "position": 1.0 // This is the position in the favorites list as a float
}

If the pin is successful, a 200 OK response will be returned. If is was unsuccessful, a 500 error response will be returned.

/gp/rest/v1/tags/repin

  • Method: PUT
  • Accepts: application/json
  • Returns:

This endpoint is used to move a favorite module in the user's list from one pinned position to another. It consumes a JSON input in the following format:

{
    "user": "The user's username",
    "lsid": "This is the LSID of the module being unpinned",
    "position": 1.0 // The NEW position of the module will be located at
}

If the repin is successful, a 200 OK response will be returned. If is was unsuccessful, an error response will be returned.

/gp/rest/v1/tags/unpin

  • Method: DELETE
  • Accepts: application/json
  • Returns:

This endpoint is used to remove ("unpin") a favorite module from the user's list. It consumes a JSON input in the following format:

{
    "user": "The user's username",
    "lsid": "This is the LSID of the module being unpinned",
    "position": 1.0 // The position of the module may be included, but is optional
}

If the unpin is successful, a 200 OK response will be returned. If is was unsuccessful, an error response will be returned.

Log

This resource allows a client to pass information back to the GenePattern server. This information gets written to the server's log. Information logged in this way can be useful for server administrators when debugging, and in recognizing common error states in the GenePattern client. Best practice is to not invoke this resource unless the client developer also administrates the connected server.

/gp/rest/v1/log/debug

  • Method: POST
  • Accepts: text/plain
  • Returns:

This endpoint accepts a text string which gets written to the GenePattern server's log as a debugging statement. If successful, this endpoint returns a 200 OK response with a blank body.

/gp/rest/v1/log/error

  • Method: POST
  • Accepts: text/plain
  • Returns:

This endpoint accepts a text string which gets written to the GenePattern server's log as an error. If successful, this endpoint returns a 200 OK response with a blank body.

/gp/rest/v1/log/info

  • Method: POST
  • Accepts: text/plain
  • Returns:

This endpoint accepts a text string which gets written to the GenePattern server's log as an informative statement. If successful, this endpoint returns a 200 OK response with a blank body.

/gp/rest/v1/log/warn

  • Method: POST
  • Accepts: text/plain
  • Returns:

This endpoint accepts a text string which gets written to the GenePattern server's log as a warning. If successful, this endpoint returns a 200 OK response with a blank body.

Config

This resource is used to query for configuration options set for the user on the GenePattern server. This allows server administrators to set configuration options, and for web apps using the GenePattern REST API to dynamically respond or change behavior based on this configuration. For example, a web app may want to offer different options depending on the version of the server it is connecting to, as newer versions of GenePattern may support newer functionality. The endpoints for this resource are as follows:

/gp/rest/v1/config/admin

  • Method: GET
  • Accepts:
  • Returns: application/json

This endpoint can be called to determine if the current user has administrative privileges on the GenePattern server. The response will be in the form of a JSON object with the following format:

{
    "result": true or false // A boolean
}

/gp/rest/v1/config/gp-url

  • Method: GET
  • Accepts:
  • Returns: application/json

This endpoint will return a URL to the GenePattern web application, including the trailing /gp/. For example, it might return http://genepattern.broadinstitute.org/gp/ as the URL. This URL will be part of a JSON object with the following format:

{
    "result": "The GenePattern URL to the GenePattern web application"
}

/gp/rest/v1/config/gp-version

  • Method: GET
  • Accepts:
  • Returns: application/json

This endpoint will return the version of the GenePattern server. The response will be a JSON object in the following format:

{
    "result": "The GenePattern version number returned as a string, for example '3.9.7'."
}

/gp/rest/v1/config/property/{propertyName}

  • Method: GET
  • Accepts:
  • Returns: application/json

This endpoint allows a developer to specify a property in the GenePattern configuration, and it returns the value of this property for the current GenePattern user. For example, making a call to /gp/rest/v1/config/genomeSpaceEnabled will return whether GenomeSpace integration is turned on for the user (by default this will be true for all users). The response will be returned as a JSON object in the following format:

{
    "result": "The value of the property returned as a string."
}

If a configuration parameter that does not exist is queried, an empty JSON object will be returned.

/gp/rest/v1/config/system-message

  • Method: GET or POST
  • Accepts: — or text/html
  • Returns: text/html or —

This endpoint can be used to GET or POST a system message for the GenePattern server.

Any valid user can get the current system message. This uses the GET method and returns the message in HTML.

Only users with administrative privileges may post a new system message. This uses the POST method and consumes a body consisting of HTML. For users without administrative privileges this will generate a 401 unauthorized response. Successfully posting a new system message will return a 200 OK response with a blank body.

/gp/rest/v1/config/user

  • Method: GET
  • Accepts:
  • Returns: application/json

This endpoint returns the username of the current user. It will be returned in a JSON object with the following format:

{
    "result": "The GenePattern username."
}

Suites

In GenePattern, suites are collections of modules organized around a particular type of analysis. As such, suites are one way of organizing modules or transporting collections of modules from one GenePattern server to another. For a list of available suites, click here.

Few recent GenePattern modules use suites, as the functionality is largely being replaced by the newer category and tag methods of organizing modules. Nevertheless, the suites resource makes obtaining a list of suites available in the GenePattern REST API. The following endpoint is available.

/gp/rest/v1/suites/all.json

  • Method: GET
  • Accepts:
  • Returns: application/json

This endpoint returns a list of JSON objects, each object representing a suite installed on the GenePattern server. When more than one version of a suite exists, only the most recent version of the suite is represented in the list. Objects are in the following format:

{
    "lsid": "Life Science Identifier (LSID) of the associated suite",
    "name": "The name of the suite",
    "description": "A description of the suite",
    "version": "The version of the suite, represented as a string",
    "tags": ["A list of tags associated with the suite"]
}

OAuth2

This resource represents GenePattern's implementation of the OAuth2 protocol. Because of its nature, authentication is not first required before using the associated endpoints. This is different from the other resources in the GenePattern REST API.

For more information on OAuth2 in general, see the OAuth2 specification.

/gp/rest/v1/oauth2/auth

  • Method: GET
  • Accepts:
  • Returns:

This endpoint is for the client to request authorization from GenePattern to make requests on the user's behalf. The following GET parameters should be included with the call:

  • response_type: This paremeter should be set to either token or code. Anything else will return an error.
    • code: Returns an authorization code that the client should return to the server for a token once a user has given permission to access their account. This should be done from a secure connection, because in a later step it will require a client secret, which must be kept confidential. It is recommended that developers never use this option from JavaScript, as by its very nature JavaScript is not particularly secure.
    • token: Returns an authorization token rather than an access code. Authorization tokens are less secure than access codes, but useful when execution cannot be kept secret.
  • client_id: This is the ID of the client accessing the information from GenePattern.
  • redirect_uri: This is the URI that the response should redirect to if successful.
  • scope: This is the scope of the access being requested. Currently the only valid scopes are users. As such, this value should be a string consisting if the GenePattern username.

If authorization is successful, the response will be a 302 redirect to the URI provided in the redirect_uri parameter.

/gp/rest/v1/oauth2/token

  • Method: POST
  • Accepts: application/x-www-form-urlencoded
  • Returns:

This endpoint generates and returns to the user an access token that can be included with requests to verify authentication. The following should be included as GET-style parameters or in the POST body:

  • grant_type: This indicates what security method is being used to grant the access token. This should only be one of the following values.
    • authorization_code: In this case an authorization code that was returned by the /gp/rest/v1/oauth2/auth endpoint is being provided to verify identity
    • password: In this case a username and password will be provided to verify identity.
    • refresh_token: This will grant a code that can be used to obtain a new access token. This is currently not implemented, and this option is a placeholder. For now, using this option will always return an error.
  • code (optional): If the authorization_code grant_type was chosen, the authorization code must be presented here and must match what was provided to the client.
  • username (optional): If the password grant_type was selected the username of the user logging in should be included here.
  • password (optional): If the password grant_type was selected the password of the user logging in should be included here.
  • redirect_uri: The response will redirect back to this URI after a token is generated. The token will be appended to the URL as a GET parameter or fragment (ex: ?code=AUTH_CODE_HERE or #token=TOKEN_HERE).
  • client_id: This is the ID of the client accessing the information from GenePattern.
  • client_secret: This is a secret code provided to the client that no one else knows that can be used to verify the identity of the client. This should only be provided if the calls can be made secretly. It is recommended that thse calls be made through HTTPS and not through JavaScript.

If authorization is successful, the response will be a 302 redirect to the URI provided in the redirect_uri parameter.

/gp/rest/v1/oauth2/register

  • Method: POST
  • Accepts: application/json
  • Returns: application/json

This endpoint isn't currently implemented. It is a placeholder for the register call in the OAuth2 specification. All calls to this endpoint currently return an error response.

Disk

This resource is used to monitor a user's disk usage. It only contains a single endpoint.

/gp/rest/v1/disk

  • Method: GET
  • Accepts:
  • Returns: application/json

When queried, this endpoint returns the current disk usage and disk quota for the user. The response will be a JSON object in the format shown below:

{
    "aboveQuota": true or false, // Whether the user is above the disk quota or not
    "diskQuota": {
        "displayValue": "Easy-to-read string representing the quota set for the user. Ex: 400 GB",
        "numBytes": 429496729600 // Number of bytes in the disk quota as an integer
    },
    "diskUsageFilesTab": {
        "displayValue": "String representing disk taken up by the user's files tab",
        "numBytes": 429496729600 // Number of bytes taken up by files in the files tab
    },
    "diskUsageTmp": {
        "displayValue": "String representing temp space taken up by the user",
        "numBytes": 429496729600 // Number of bytes taken up by the user's temp space
    },
    "diskUsageTotal": {
        "displayValue": "String representing the user's total disk usage",
        "numBytes": 429496729600 // Number of bytes taken up by the user's total disk usage
    },
    "userid": "The username of the current user."
}

RunTask

Those exploring the GenePattern WADL file may notice that one additional resource is defined at /gp/rest/RunTask. Unlike the other resources, this one is not versioned.

This is a deprecated resource that still exists for reasons of backward compatibility. We do not recommend using this resource in your development, as it may be removed in an upcoming version of GenePattern. Instead we recommend using the Tasks resource for similar functionality.