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.
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 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).
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.
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:
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).
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.
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.
Content coming soon
Content coming soon
Content coming soon
Content coming soon
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.
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"
}
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.
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.
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.
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.
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.
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.
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.
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.
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:
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
}
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"
}
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'."
}
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.
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.
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."
}
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.
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:
If authorization is successful, the response will be a 302 redirect to the URI provided in the redirect_uri parameter.
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:
/gp/rest/v1/oauth2/auth endpoint is being provided to verify identityIf authorization is successful, the response will be a 302 redirect to the URI provided in the redirect_uri parameter.
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.
This resource is used to monitor a user's disk usage. It only contains a single endpoint.
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."
}
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.