-
Notifications
You must be signed in to change notification settings - Fork 1
API Reference
Wiki ▸ API reference
Root URL for all GIANT API calls is giant-api.princeton.edu. The API endpoint for any function is simply the function name appended to the API root. For example, the endpoint for tissues is giant-api.princeton.edu/tissues. Calls made to this endpoint will always refer to the most recent version of the API. To refer to a specific API version, you can optionally append the version number, in (major version).(minor version), format to the default endpoint. For example, giant-api.princeton.edu/tissues/0.1 will use version 0.1 of the API.
API responses can be returned either in JSON or HTML. JSON is the default for non-browser clients (e.g., cURL or AJAX requests) and HTML is the default for browsers, which makes it easier to visualize results. If JSON output is desired on a browser, the default setting can be overridden using the format form field. For example, http://giant-api.princeton.edu/tissues?format=json will always return a JSON response even on a browser. Similarly http://giant-api.princeton.edu/tissues?format=api will always return an HTML response even on a command line client.
Tissue-specific functional networks for human (aka GIANT)
Global functional networks for multiple organisms (aka IMP)
NetWAS
Helper functions
# GET /networks/:tissue/:gene[+:gene2[...]]
Returns the functional gene network for a specified tissue (:tissue) and a set of of one or more genes (:gene). For a list of valid tissue names, see tissues; for a list of valid gene names, see genes. By default the vertices of the network will be the query genes plus 50 other functionally-related genes. There is no restriction on the number of edges in the network. The default prior probability used for network prediction is 0.1. The default values for both the number of vertices and the prior can be overridden using the POST version of the same query, which supports additional parameters.
# POST /networks
Same as the previous networks function except that the arguments are passed via POST fields instead of being embedded in the URL. This format supports 2 additional parameters which cannot be easily encoded in a clickable URL.
| Parameter | Description |
|---|---|
tissue |
Tissue name. See tissues for valid tissue names. |
gene[+gene2[...]] |
One or more gene names. See genes for valid gene names. |
[size] |
Number of genes in the network in addition to the query genes (default = 50) |
[prior] |
Prior probability used in predictions (default = 0.1) |
# POST /networks/evidence
The networks/evidence endpoint is used to query datasets (i.e., evidence) supporting a predicted functional relationship between any two genes in a tissue context. The tissue is specified using the tissue parameter, and the gene pair is specified using the source and target parameters.
| Parameter | Description |
|---|---|
tissue |
Tissue name. See tissues for valid tissue names. |
source |
Name of the first gene in a gene pair. See genes for valid gene names. |
target |
Name of the second gene in a gene pair. |
# GET /imp/:organism/:gene
Returns the functional network for a specified organism (:organism) and a gene (:gene). The result graph contains all edges with weights of at least 10%. The following 7 organisms are currently supported:
| Organism | Alternative specifier(s) |
|---|---|
worm |
c_elegans |
zebrafish |
d_rerio |
fly |
fruitfly, d_melanogaster
|
human |
h_sapiens |
mouse |
m_musculus, mus_musculus
|
rat |
r_norvegicus |
yeast |
s_cerevisiae |
# POST /netwas
Creates a new NetWAS job on GIANT server. Job parameters are passed via POST fields.
| Parameter | Description |
|---|---|
gwas_file |
Path to the input GWAS file |
gwas_format |
Format of the input GWAS file. Valid options are (vegas, forge, pseq). |
tissue |
Tissue name or one of 4 demo mode specifiers (see below) |
p_value |
Positive p-value threshold |
[title] |
An optional descriptive name for the job |
[email] |
An optional email address which will receive notification of job results |
Valid tissue names can be any of the 144 tissues covered by GIANT (see tissues) or one of 4 demo mode specifiers, which are (api-demo, api-demo2, api-demo3, api-demo4). Using one of these demo options will simulate a short NetWAS jobs on the GIANT server, which is intended to help with testing since actual NetWAS jobs may take a long time to complete (typically 15 to 30 minutes).
If a new job has been successfully registered, this function will return a response echoing back the input parameters specified by the user, plus some additional information including a unique job ID, which can later be used to start the job, track its progress, and view its results.
# GET /netwas/:id
Returns status information for a NetWAS job identified by the specified job ID (:id). Status response includes all the input parameters specified by the user when the job was created, the job ID (assigned by the GIANT server), various timestamps (e.g., job creation time), job status (e.g., not started, queued, running, or completed), link to a log file that can be used to view the job progress if it has started, and link to a results file that can be downloaded if it has completed.
# POST /netwas/:id/start
Starts SVM training for the NetWAS job identified by the specified job ID (:id). A job can only be started if it's not already running or has not completed. Returns a response indicating whether the job has been successfully queued. Job progress and results can later be queried using netwas/:id.
# GET /tissues
Returns a sorted array containing names of the 144 human tissues recognized by GIANT. If, instead of an array, a JavaScript object is desired, this can be specified by appending the form field container=object to the URL. This will return an associative array where keys are tissue names and values are null.
By default tissue names are all lower case and multiple words are separated by underscores. This can be changed by appending a case specifier to the URL, which can be set to t or s. This is useful when programmatically building HTML forms, e.g., a select field whose options are all the tissues supported by GIANT.
# GET /tissues/:tissue[+:tissue2[...]]
Verifies if the specified tissue name[s] (:tissue) are valid and recognized by GIANT. Returns an array containing standardized tissue names in the same order as they are given in the input. If a tissue name is invalid, the corresponding array entry will be null. A more detailed view is available when verbose=true is appended to the URL. This replaces each array entry with an object containing the tissue name as queried, the corresponding standardized name, and a valid flag.
# GET /genes
Returns a sorted array containing names of all human genes recognized by GIANT. Gene names (symbols) conform to the HGNC standard. An associative array can be requested instead of an array by appending container=object to the URL.
# GET /genes/:gene[+:gene2[...]]
Verifies if the specified gene name[s] (:gene) are valid and recognized by GIANT. Returns an array containing gene names (converted to HGNC standard symbols) in the same order as they are listed in the input. A more detailed view is available when verbose=true is appended to the URL. This replaces each array entry with an object containing the gene name as queried, the corresponding systematic and standardized names, gene's entrez ID, and a valid flag.