1 General Information
1.1 Introduction
The InterMine Web Service was created for users who want to 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://www.flymine.org/query/service/template/results?name=AllGene_Chromosome&constraint1=Gene.organism.name&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.
1.2 Querying from your program
You can query InterMine easily 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 being developed.
1.3. Download Java client
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.
| Current version | intermine-client-1.0.zip |
| Previous version | flymine-release-15.0-client.zip |
1.4 Request URL Construction
All request URLs start with the hostname of the server, and resemble the following example:
http://www.flymine.org
After the hostname is the service name path followed by a question mark:
http://www.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://www.flymine.org/query/service/template/results?name=AllGene_Chromosome&constraint1=Gene.organism.name&op1=eq&value1=Drosophila+melanogaster&size=10&format=html
1.5 Parameters description
This table contains description of parameters common for more web services.
| Parameter | Value | Description |
| size | integer: default 10, max allowed value 1000 000 | Maximum number of results to be returned. |
| format | xml, tab, csv, html: default tab | Format of the output. It can be XML, HTML or lines with tab separated or comma separated values. |
| layout | string, optional | Specifies layout of results html table. It has sense only for query and template results service and if the format parameter equals html. It is formed by options separated by | Specify following options if you want corresponding element to be displayed. title - table title description - table description mineresults - link to results page on website providing this service paging - links for paging through results newwindow - link for opening in new window mine - link to website providing this service example: layout=title|description|mine |
1.6 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>
1.7 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. |
| 500 | Service internal error. An internal problem prevented us from returning data to you. |
| 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.
1.8 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.
1.9 How to find a version of the web service you are connecting to
Go with your browser to the following address: http://server_name/query/service/version Replace 'server_name' with your real server name. On this page you can find the version of the web services provided by the server. If browser displays message that the page with that address doesn't exist then the version number is 0 or web services are not implemented. Version numbers for FlyMine and ModMine?.
| Server | Web services version |
| FlyMine version 14, 15 | 0 |
| FlyMine version 16 and newer | 1 |
| ModMine version 4 - 7 | 0 |
| ModMine version 8 | 1 |
| FlyMine version 13 and older | Not implemented. |
Flymine version 15, Modmine version 7.
1.10 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
2 Services overview
2.1 Query web service
This page describes the InterMine query web service. With this service you can include query results in your web site or automatically generate links and download data with a script. Results can be obtained in various formats. For general information about InterMine web services see WebService.
2.1.1 Quick HOW TO
Example link: http://www.flymine.org/query/service/query/results?query=%3Cquery%20model=%22genomic%22%20view=%22Gene.name%20Gene.organism.name%20Gene.length%22%20sortOrder=%22Gene.name%20asc%22%3E%3Cnode%20path=%22Gene%22%20type=%22Gene%22%3E%3C/node%3E%3C/query%3E There is only one parameter - query, containing a query as an xml string. The string must be URL encoded.
Parameter description
| Parameter | Value | Description |
| query | xml string | This is the most important parameter and it is always required. It specifies what data you want to get and constraints on the data. So you can precisely select the data you want to get. You can construct the query or use an exported query from InterMine (FlyMine) |
Other parameters: start, size, tcount, format. For more information see Parameters description.
2.2 Template web service
This page describes the InterMine template web service 1.0 and how to construct links to get the results of a particular template. Please click here for help how to find a version number of the InterMine server you want to connect to. If you are connecting to the server with web services version 0, then please follow this documentation. With this service you can include template results in your web site or automatically generate links and download data with a script. Results can be obtained in various formats. For general information about InterMine web services see WebService.
2.2.1 Quick HOW TO
1.Simple template:
Example link: http://www.flymine.org/query/service/template/results?name=AllGene_Chromosome&constraint1=Gene.organism.name&op1=eq&value1=Drosophila+melanogaster&extra1=&format=html&size=10
In this replace AllGene_Chromosome with name of your template, Drosophila+melanogaster replace with required organism name and eq replace with abbreviation of your operation.
If you want to get 50 results replace 10 by 50.
2.Template with lookup:
Example link: http://www.flymine.org/query/service/template/results?name=Gene_ExonLocation2&constraint1=Gene&op1=LOOKUP&value1=CG1046&extra1=&size=10&format=html
In this case operation LOOKUP means that CG1046 will be searched for in gene identifiers, gene synonyms, secondary identifiers and so on. It solves problems with gene identifier ambiquity. So replace CG1046 with your gene identifier.
2.2.2 Important notices
- '+' is an encoded space character, eg 'Drosophila+melanogaster'. Some special characters in URL must be encoded.
- InterMine can generate the link for you. Go to a template page and click on the 'Embed' link at the bottom of the form.
2.2.3 Detailed parameter description
| Parameter | Value | Description |
| name | string | Template name. |
| constraint1 | string | Constraint path. It is used as a identifier to determine constraint corresponding this path in template and initialize this constraint with operation specified in 'op1' parameter and with value specified in 'value1' parameter. When there are more constraints for the same path, then you must provide additional 'code' parameter. |
| code1 | string | Code of constraint. Required only if there are more constraints on the same path. |
| op1 | string | URL encoded operation of constraint. Required. Following table shows permitted operations. |
| value1 | string | URL encoded value of constraint. Required. |
| extra1 | string | URL encoded extra value. Used and required when the constraint is LOOKUP. It searches for the identifier provided in the value1 parameter in all identifier fields like synonym, primary identifier, secondary identifier and restricts results to the organism specified in the extra1 parameter. |
Other parameters: start, size, tcount, format. For the description see Parameters description
If the template has more constraints there will be more parameters like op2 and value2, and all the parameters are required.
2.2.4 Operations
| Operation | Encoded operation | Abbreviation |
| = | %3D | eq |
| != | %21%3D | ne |
| < | %3C | lt |
| <= | %3C%3D | le |
| > | %3E | gt |
| >= | %3E%3D | ge |
Encoded operation or corresponding abbreviation can be used in URL.
2.3 List Web Service
This page describes the InterMine lists web service and how to construct links to get all lists containing specified object. For general information about InterMine web services see WebService.
2.3.1 Quick HOW TO
Example link: http://www.flymine.org/query/service/listswithobject?publicId=FBgn0000606&type=Gene This link returns all public lists with object of type Gene with id FBgn0000606.
2.3.2 Detailed parameter description
| Parameter | Value | Description |
| publicId | string, required | Id of object. |
| type | string, required | Type of object. |
