Webace API

This is a document of examples, based on the Chromosome 1 database at The Sanger Centre, but which can be adapted for use with any webace served acedb database.

The full syntax definition is listed below

HREF examples

It should be noted that any URL, including a query, can be stored as a URL object in any acedb database as well on a static page. This allows you to embed crosslinks to other acedb databases of both an static and active (query) nature.

1. List Classes in Chromosome 1 database.

Specifying just a db will list all the classes in it.
http://webace.sanger.ac.uk/cgi-bin/webace?db=acedb1

2. List Maps in Chromosome 1 database.

Specifying a db and a class will list all the objects in it.
http://webace.sanger.ac.uk/cgi-bin/webace?db=acedb1&class=Map

3a. Show Overview Map of Contigs in Chromosome 1 database.

Specifying a db, class and object will display the object.

Calling display will display it graphically if possible (i.e. if class = Sequence or Map). Including display=active will turn mouseover functionality (using java or javascript) on.
http://webace.sanger.ac.uk/cgi-bin/webace?db=acedb1&class=Map&object=Chr_1
&display=active

Calling webace will display it as text, provided the display=text parameter is added.
http://webace.sanger.ac.uk/cgi-bin/display?db=acedb1&class=Map&object=Chr_1
&display=text

3b. Show Top region of Overview Map of Contigs in Chromosome 1 database.

It is possible to specify the graphical display of a particular region using the begin and end parameters.
http://webace.sanger.ac.uk/cgi-bin/webace?db=acedb1&class=Map&object=Chr_1
&begin=0.0&end=220.0

3c. Show above with default view, rather than autoselected 'chr' view.

Where 'views' have been defined (for either Sequence or Map objects) by the curator using a webace_view.pl file, these can be selected using the view parameter. If the view specified is unknown the the default view will be shown, as it is defined in the webace_view.pl definition file.

In this case if view is not given, the 'chr' view is autoselected by webace (as defined in webace_view.pl). This can be overridden to display the 'def' view as shown here.
http://webace.sanger.ac.uk/cgi-bin/webace?db=acedb1&class=Map&object=Chr_1
&begin=0.0&end=220.0&view=def

3d. Show text view of Chr_1 object with list of maps shown.

It is also possible to display how text objects are displayed. Many objects contain long lists of different feature types. By default, where a list has more than 7 elements, the list is contracted to an expand link. Clicking on such a link will return the same object with this list expanded. If you examine the URL in your browser after such an expansion you will see that an extra parameter has been added of the form seme=X, where X is a number. If multiple lists have been expanded you will see seme=X.Y.Z, i.e. a number, separated by a decimal, for each list expanded. To show a view with a particular expansion directly, add the seme with an appropriate qualifier to the URL.

To show the Chr_1 Map object with the full list of maps, add seme=5
http://webace.sanger.ac.uk/cgi-bin/display?db=acedb1&class=Map&object=Chr_1
&display=text&seme=5

4. Use query to extract a particular sublist

In 2. db and class parameters were used to list all objects in a class (in this case all maps). A refinement might be to only list contig maps. This can be specified using the query parameter, which allows a full ace query to be specified. Note that one difficulty in this is that special characters, such a spaces in the query must be encoded as specified here.

http://webace.sanger.ac.uk/cgi-bin/webace?db=acedb1&query=find%20Map%20Chr_1ctg*

5. Use query to find a particular entry that is not static

Contig maps are frequently superceeded as gaps are closed. When embedding a reference to the map for a sequence object, it may therefore be better to express this as a active (query) rather than a static link.

http://webace.sanger.ac.uk/cgi-bin/webace?db=acedb1&query=find%20Sequence%20dJ8B22%3Bfollow%20Map

Form examples

1. Keyword search Below is the code required to implement a keyword search of the Chr_1 database and a working example of its implemented form.

<form method=GET action="http://webace.sanger.ac.uk/cgi-bin/webace">
<input type=hidden name="db" value=acedb1>
Enter search word: <input name="grep" size=20>
[<input type="checkbox" name="longgrep" value=1>Do full search]
<input type="submit" value="Search">
</form>


Enter search word:  [Do full search] 

<form method=GET action="http://webace.sanger.ac.uk/cgi-bin/webace">
<input type=hidden name="db" value=acedb1>
<input type=hidden name="prequery" value="find Sequence ">
<input type=hidden name="postquery" value=";follow Map">
Enter sequence objectname: <input name="query" size=20>
<input type="submit" value="Search">
</form>




Enter sequence objectname: 

Syntax

Note: The two scripts will also in some cases automatically redirect to the other script if you called the wrong one, i.e. any call without db, class and object will be passed to webace and any call with db, class and object, where class = Sequence or Map and display != text will be passed to display, however this behaviour should not be relied upon as its is slower (requires 2 CGI calls instead of one) and it is not guarenteed that all parameters will get passed. This property exist mainly to implement error recovery and is mentioned here only as a warning: if a call behaves roughly as expected, but some parameters are ignored check you are not calling the wrong CGI in the first place!

The most useful and stable parameters of the API are listed below.

Name	Parameter	CGI	Values	Example	Description
Database	db	W,D	<databasename>	db=acedb1	Any database listed in
Class	class	W,D	<acedbclass>	class=Sequence	Any class in the acedb database specified by the db parameter
Object	object	W,D	<objectname>	object=dJ296K21	Any object in the class of the acedb database specified by the class and db parameters respectively
Display Mode	display	W,D	text graphics active	display=text	Only affects display of objects with class Sequence and Map. active mode is a graphical display with mouseover turned on.
Range start	begin	D	<number>	begin=10.2	Beginning of range to be displayed: can be real for Maps, but should be integer for Sequence.
Range end	end	D	<number>	end=100.8	End of range to be displayed: can be real for Maps, but should be integer for Sequence.
Expansion	seme	W	<number[.number]>	seme=1.4.2	Qualifier is a list of the indices of sublists in a text object that are to be expanded. Order is not relevant
View Control	view	D	<viewname>	view=def	Valid viewnames will are defined for Sequence and Map views by the database curator. A default behaviour will result if an invalid viewname is given.
Query	query	W	<aceclient query>	query=find%20Sequence%20dJ*	Any acedb query can be specified by encoding the special characters in the string with the rules listed below.
Search	grep	W	<keyword>	grep=human	Shortcut to enable keyword searching using ace query 'grep' command to be called easily from a form (see example).
Search qualifier	longgrep	W	button	grep=human	Qualifier for use with grep parameter to select ace query 'longgrep' instead of 'grep'.
PreQuery	prequery	W	<part of aceclient query>	prequery=find%20	Allows query string to be assembled with constant and variable fragments in a form (see example).
PostQuery	postquery	W	<part of aceclient query>	postquery=%3Bfollow%20Map_link	Allows query string to be assembled with constant and variable fragments in a form (see example).
Bypass cache	nocache	W,D	1	nocache=1	Forces the query to ignore cached files and requery the acedb database. Useful for testing and if an error occured when the original cache file was being generated.

If you examine the URL you will find a number of other parameters, however most are there for reasons to do with HTML form management and cannot be usefully used to extend the API.

CGI URL qualifiers encoding

Character	Encoded String
<space>	%20
"	%22
%	%25
'	%27
/	%2F
:	%3A
;	%3B

Thus, to refer to the object em:Z12345 you would write em%3AZ12345 in any URL