Welcome to the GenomeQuest Documentation Wiki
URL API
Contents |
Introduction
This layer provides calls formed with URLs that can be used three ways:
- Directly from the navigation toolbar of a web browser. GQ URLs allow changing GQ GUI default’s display and output stream.
- From external Web applications. GQ URLs can be inserted with simple, single-link call. This allows quickly connecting in-house application from / to the GQ platform.
- As a more advanced use, URLs can be used in a programmatic way, using regular programming languages.
The GQ URL API obeys the standard type of operations. It uses HTTP-encoded requests to GenomeQuest Web server. It is very similar in its principle and use, to other approaches such as the NCBI one . However, while it can perform the same types of operations, the GQ URL API provides extended capabilities compared to legacy tools.
The general form of an URL is:
http://www.gqserver.com/query?
do=<operation> &
param1=value1 &
param2=value2
do= is the main operation dispatcher. Four major operations are provided: gqfetch, gqworkflow, gqresult, gqplugin. A significant number of other operations are available, however these are the more common operations.
Help Online
The URL API's documentation is built into the GenomeQuest system. Try:
Each of the major dispatchers listed there (e.g., gqfetch, gqresult, etc.) have their own help systems:
Use Cases
Get a Token
Log into the system programatically.
[Request] http://server/query?do=gquser.get_token&username=[username]&password=[password]&apitokenttl=[3600]
[Response] token = 4:oenfcwuWe09e token_creation_date = server Unix timestamp for token’s creation time token_expiration_date = server Unix timestamp for token’s expiration time expired = 0 | 1 (0 for not expired, 1 for expired)
Fetch a Sequence Database
Assumes you already have an API token or are logged in via a browser.
[Request] http://server/query?do=gqfetch&db=GB_VRL&template=printf:%H%23ID\n&apitoken=xxx
Please note '%23' in above URL is '#' character in encoded form. template=printf:%H#ID\n specifies the data to be returned, in this case '%H#ID\n' means return all ids of sequences in Genbank Viral division, separated by carriage return. By default it only returns first 50, you can add &start=x&stop=y to control how many records to return.
Run an IP Sequence Search
[Request]
http://server/query?do=gqworkflow &
workflow_type = GqWfIpSearch &
qdb_seq_type = nucleotide|protein &
qdb_seq = ATGCATGC &
sdb_def_id = GQPAT_NUC,GQPAT_PRT &
strat_name = blast|kerr|fragment &
strat_{$strat_name}_best_hit_keep_max' = 500 &
title=my ip search &
... (other strategy specific params, see below)
if strat_name is
blast:
strat_blast_best_hit_definition = EVAL|SCORE & strat_blast_word_size_nuc = 11 & // or strat_blast_word_size_pro = 5 in case there is protein qdb or sdb involved. strat_blast_eval_cutoff = 10 &
kerr:
strat_genepast_perc_id = 80 & strat_genepast_perc_id_over = QUERY|SUBJECT|SHORTER &
Run a Sequence Search
[Request]
http://server/query?do=gqworkflow &
workflow_type = GqWfSeqSearch &
qdb_seq_type = nucleotide|protein &
qdb_seq = ATGCATGC &
sdb_def_id = GB_PRI &
s = OS="Mus musculus" & // a filter applied to subject sequence database - OS field matches "Mus Musculus"
strat_name = blast|genepast|fragment|motif|hs3 &
strat_{$strat_name}_best_hit_keep_max' = 500 &
title=my blast of gb_pri &
... (other strategy specific params, see below)
if strat_name is
blast:
strat_blast_best_hit_definition = EVAL|SCORE & strat_blast_word_size_nuc = 11 & // or strat_blast_word_size_pro = 5 in case there is protein qdb or sdb involved. strat_blast_eval_cutoff = 10 &
genepast:
strat_genepast_perc_id = 80 & strat_genepast_perc_id_over = QUERY|SUBJECT|SHORTER &
The format=json will return the result in a parsable JSON string. It will return a workflow_id that you can use in future queries against the result of this search.
Check Workflow run status
Assuming you launched a workflow and get the $workflow_id in return.
[Request]
http://server/query?do=gqworkflow.get_status&workflow=id:{$workflow_id}&format=json
You will get a data structure similar to this after json decode:
[status] => FINISHED [progress] => 100
Examining Workflow Result
Assuming you launched a workflow and get the $workflow_id in return.
Each workflow could produce different outputs, assume the one of the outputs is named $output_name, See below for how to list all outputs of each workflow type.
[Request]
http://server/query?do=gqworkflow.show_result&workflow=id:{$workflow_id}&workflow_output_name={$output_name}
You can continue to append other output specific params to the URL to change the return value.
For example, if you know that output is an alignment database, you can append template parameter to ask system to output the result in specified format:
- template=printf:%25RE%25HD%23ID %25HD%23PN %25HD%23PA\n.
%25RE %25HD%23ID %25HD%23PN %25HD%23PA\n is the url-encoded string for %RE %HD#ID %HD#PN %HD#PA\n, which is slightly easier to read. This is what we call a printf template that specifies what data in what format do you want to retrieve from a result. It says "give me all subject hits, each line should contain eval and identifier and patent number and patent assignee."
- template=printf:%25RESCNT%25PRE.
%25RESCNT%25PRE (aka %RESCNT%PRE on the command line) returns the total number of results.
The response of this request (gqworkflow.show_result) is often a http redirect header, which will lead to the proper page that displays the result, so please make sure your client handles the redirect properly.
See all the outputs enlisted in a workflow type
Each workflow type could potentially produce different outputs, including multiple alignment databases, or sequence databases, or spreadsheet, etc.
Use this URL to find out all the outputs produced by a Seq Search workflow
[Request] http://server/query?do=gqworkflow.get_outputs&workflow_type=GqWfSeqSearch
And for IP workflow
[Request] http://server/query?do=gqworkflow.get_outputs&workflow_type=GqWfIpSearch
Check the token status
You received a token and you want to make sure it is still active.
[Request] https://server/query?do=gquser.check_token&apitoken=4:oenfcwuWe09e
[Response] similar to the response of get_token.
Delete a token
Drop your token - log out.
[Request] https://server/query?do=gquser.delete_token&apitoken=4:oenfcwuWe09e
[Response] similar to the response of get_token.
