The Reflect API

The Reflect service identifies and ‘tags’ biologically and chemically relevant names found in HTML documents. Clients provide the documents as input in HTTP GET and POST messages and, in the response, receive tagged versions where recognized names are appropriately highlighted and linked to information popup windows.

Tagging a simple document

The easiest way to illustrate how tagging works is to look at an example. Clients have to send a document to the Reflect server by sending a message containing the HTML document. Lets say we would like to tag the following very small HTML document:

<html><head></head><body>COX-2 is a target of Aspirin.</body></html>

Here is the list of things you have to do in order to have this text tagged. First, create a URL pointing to the reflect server like:

http://reflect.ws/REST/GetHTML

This URL specifies that you have chosen the REST API, selecting the GetHTML method. Then set a paramter called ‘document’ to the text mentioned above leading to:

http://reflect.ws/REST/GetHTML?document=<html><head></head><body>COX-2+and+Aspirin</body></html>

Now take this URL and copy it into the address field in your browser and press enter. You should then receive a tagged version of the document.

The structure of the call is very simple:

	[http://reflect.ws] / [REST] / [GetHTML] ? [document=...]

or

	[URL] / [interface] / [method] ? [param=value [&]]*

The first part specifies the website (URL) followed by a selection of the protocol (interface) and then the method (method) to call. All methods takes at least one parameter that must be specified in the call after the question mark (?). The method GetHTML, as a minimum, requires that you have set the document parameter. All other parameters have default values if not set.

FuntionDescription
GetHTMLTags input an HTML document.
GetURISame as GetHTML but returns a link to the tagged version.
GetEntitiesSame as GetHTML but returns only the information of the identified names.
ResolveNameSame as GetEntities but resolves the meaning of a single name.
GetPopupGet the popup for a single name.
AddNameAdds a name of a chemical, gene or protein to the list of known names.
AllowNameAllows the tagging of an otherwise blocked name on a given page.
BlockNameBlocks the tagging of an otherwise allowed name on a given page.

Examples of the use of parameters (their names and meaningful values) are shown in the sections below. Notice that a list of HTTP parameters must begin with ‘?’ after the function in the URL and that subsequent parameters must be separated with the ampersand (&).

AddName, BlockName and AllowName

http://reflect.ws/REST/AddName?name=MyName&entity_type=9606&
entity_identifier=ENSP0000xxxxxx&document_id=mydoc.txt

http://reflect.ws/REST/BlockName?name=MyName&document_id=mydoc.txt

http://reflect.ws/REST/AllowName?name=MyName&document_id=mydoc.txt

ResolveName and GetPopup

http://reflect.ws/REST/ResolveName?name=MyName

http://reflect.ws/REST/GetPopup?name=MyName

GetHTML, GetEntities and GetURI

This function can take the most parameters but a simple call could look like this:

http://reflect.ws/REST/GetHTML?document=this+is+aspirin&entity_types=9606+-1

One can specify CSS styles to be used for the entity-types mentioned by adding the following parameters:

entity_styles=css1+css2

If none is specified you will get the default CSS styles for those entity-types. You may also specify that you want to have the system auto-detect species for you by setting:

auto_detect=1

And you can also have the system look for DOIs (Digital Object Identifiers) automatically using the first DOI found in the document by setting:

auto_detect_doi=1

One may specify the following document identification parameters:

pmid=1234567
doi=10/1234/abc.9876
url=http%3A//myplace.org/mypage.html

It must be mentioned that you should use POST HTTP requests to transfer documents and not the GET request. The POST request allows you to transfer real-sized documents and papers. The GET method can only transfer a max. of 2 Kb. In either case, you will have to set the document parameter in the body of the POST request and remember to URL-encode the document text or HTML. This is very important to remember.