Anno-J Services

A 'service' in Anno-J (often referred to as a fetcher) is is a small program that sits out on the web somewhere and responds to simple HTTP requests with sensible data. For example, a time fetcher might respond to the query: http://www.somesite.com/service?tellTime with a response of 09:30:00 AM. From the client's perspective, the fetcher's implementation details are irrelevant.

Anno-J is a client and it's important to realize that it does not store data: it is a REST-based, 100% server-side agnostic application. It is the responsibility of the data provider, not the client, to maintain, curate, secure, syndicate, and host his/her own data.

This section provides an example of how to create a server-side fetcher that provides Gene Model annotation data in response to simple HTTP GET requests (conveniently the same requests that an Anno-J GeneModels plugin uses). The example uses MySQL, PHP and Apache but does not depend upon these technologies.

1. Preparing Data
2. Service Syndication
3. Responding to Requests
4. Registering the Service (optional)
5. Conclusion

Responding to Requests

Now that syndication has been sorted out, the next step is to actually respond to requests for data with response objects serialized as JSON strings. There are two possible courses of action here:

1. You respond with any data structure you want to, putting responsibility for handling in the hands of plugin developers.
2. You look up the list of data types and respond with an existing data structure.

Take a look at the list of data types and the list of plugins for more information.

In this example (written in PHP), the request will be made to a service that provides information about gene models. The request will be a standard range request and the response will be in models format, suitable for use with a ModelsTrack.

		/**
		 * Example of PHP code that provides gene-model data in response to a range request.
		 * Rendering is carried out by a ModelsTrack.
		 */
		if ($action == 'range')
		{
			$query = "select parent, id, strand, class, start, end-start+1 from $table where 
			          assembly='$assembly' and start <= $right and end >= $left order by start asc, end desc";
			
			if (cache_exists($query))
			{
				cache_stream($query);
			}
			
			$d = query($query);
		
			$data = array();
		
			while ($r = mysql_fetch_row($d))
			{
				$r[4] += 0;
				$r[5] += 0;
				
				//Skip if too small to be seen anyway
				if ($r[0] && round($r[5] * $pixels / $bases) == 0) continue;
				
				$data[] = $r;
			}
			cache_create($query, $data, true, $table);
		}
		error('Invalid action requested: ' . $action);