InterMine Web Service

• General information
  • Introduction
  • Request URL Construction
  • Parameters description
  • Error messages
  • Output format
  • POST
  • Querying from your program
  • Disabling web service
• Services overview
  • Service returning query results
  • Service returning template results
  • Service returning lists with specified object

Introduction

The InterMine Web Service was created for users who want access the data of InterMine not only clicking at the links in the browser but from their own web pages or applications. If you want to use the InterMine Web Service you should have basic knowledge of what a http request is and how to send a request from your program and get the results. You can use the POST or GET method when submitting your request. You should use POST when your request is larger than 1 kB. For more information see the POST section.

We will use the FlyMine web service to demonstrate this InterMine feature throughout this document. FlyMine is an instance of InterMine. The easiest way to play with InterMine web services is to put this address in your browser:

http://flymine.org/query/service/template/results?name=AllGene_Chromosome&op1=eq&value1=Drosophila+melanogaster&size=10&format=html

In addition to using a browser, you can send this request from your own program and get the results as tab-separated values or xml as well. The URL is case sensitive, and parameters are lower case.

Request URL Construction

All request URLs start with the hostname of the server, and resemble the following example:

http://flymine.org

After the hostname is the service name path followed by a question mark:

http://flymine.org/query/service/template/results?

This base URL is followed by the actual query parameters, which take the form argument=value, where the arguments and values are url encoded. You can encode your URL with http://tools.devshed.com/webmaster-tools/url-encoding tool. Multiple parameters are separated by an ampersand (&). The following example returns from FlyMine first 10 result of public template AllGene_Chromosome.

http://flymine.org/query/service/template/results?name=AllGene_Chromosome&op1=eq&value1=Drosophila+melanogaster&size=10&format=html

Parameters description

This table contains description of parameters common for more web services.

Parameter	Value	Description
start	integer: default 1	The starting result position to return (1-based).
size	integer: default 10, max allowed value 1000 000	Maximum number of results to be returned.
tcount	yes, no: default no	Set true if you want to get count of all results. This can be time consuming, so it should be used only if needed. If the output format is xml, the count is returned in the xml header. If the format is tab, then only the count of results is returned and no other data.
format	xml, tab, html: default tab	Format of the output. It can be xml string, lines of text with tab-separated values or simple HTML.

Output format

The web service can return data in tab-separated values format, XML format or simple HTML format. The XML format is intuitive, see example:

<?xml version="1.0" encoding="UTF-8"?>
<ResultSet firstResultPosition="1">
<Result><i>(6-4)-photolyase</i><i>Drosophila melanogaster</i><i>2442</i></Result>
<Result><i>(A+T)-stretch binding protein</i><i>Drosophila melanogaster</i><i>2310</i></Result>
</ResultSet>

Error Messages

If there is a problem serving your request, you'll receive a response with an HTTP error code and an XML error response. Following is a list of the HTTP error codes you may encounter:

Code	Description
400	Bad request. The parameters passed to the service did not match as expected. The message should tell you what was missing or incorrect.
403	Forbidden. You do not have permission to access this resource.
503	Service unavailable. An internal problem prevented us from returning data to you.

XML Error example

<error>    
    <message>
        invalid query parameter (empty or missing)    
    </message>
</error>

Some errors can happen during execution of the service, so always check that there isn't any error message at the end of the ResultSet, because the data can be incomplete.

Post

Using POST is very similar to using GET. The query parameters are passed in the POST data block. They still take the form argument=value and are properly url encoded. Multiple parameters are separated by an ampersand. If you are sending a request from the browser, you will need to create a form with the parameters and set the method to POST.

Querying from your program

You can query InterMine from every programming language but for Java there is prepared Java library that you can use and that makes it very easy. Perl library is now developed. All you need is download the distribution package, see included samples and modify it for your needs. For more information see README in the distribution package. Download now.

Disabling web service

This concerns only users that install their own InterMine web application. Web service can be disabled by inserting 'webservice.disabled=true' into the build.properties.your_intermine file of your installation. By default, web service is enabled.

Final notice: InterMine web service was inspired by Yahoo Web Search Service