Difference between revisions of "GMOD RPC API"

Latest revision as of 23:02, 15 August 2013

1 Document Status
2 Background
3 Members
4 Goals
5 Related projects
6 Data classes
7 API Version
8 Data version
9 Result dates
10 Return types
11 Compression
12 Supported HTTP methods
13 Querying or Filtering by Organism
14 Pretty URLs
15 Language Implementation Pages
16 Error handling
- 16.1 HTTP error code 400
17 Use Cases
18 Services
- 18.1 Searches
- 18.2 Fetching
  - 18.2.1 Gene records
  - 18.2.2 Sequence
19 TODO

Document Status

In progress.

Background

This effort was started after Josh Goodman's talk at the January 2009 GMOD Meeting meeting titled "MOD Web API (A RESTful interface for MODs)". The main idea is to increase interoperability among the various model organism databases by creating an easy to use high level RESTful API. The queries iterated below are currently in the proposal stage and have no been implemented at any MOD.

Members

Josh Goodman - FlyBase
Robert Buels - Sol Genomics Network
Richard Smith - InterMine
Giles Velarde - GeneDB
Todd Harris - WormBase
Jim Hu - EcoliWiki
Alex Kalderimis - InterMine
Add your name here

Goals

Data model agnostic
Programming language agnostic
Easy to use
Versioned URLs for API stability over time

Related projects

Data classes

At present, this API only covers querying and retrieving information for the gene data class.

API Version

In order to provide a stable URL API all web calls should be versioned according to what version of the GMOD REST API they are using. The version number included in the URLs corresponds to the API version and not the data version. As changes to the API are made the version number will be incremented. Access to the older API versions should be provided indefinitely.

Current GMOD REST API Version: 1.1

Data version

The search results must contain an XML tag called data_version that contains the database release number. If the database does not use release numbers then the date for when the entire data class was updated should be used. If that is not available or if individual records within a data class are updated and released asynchronously then a timestamp derived from the time of query execution should be used.

For example, FlyBase releases its data on a roughly monthly basis and tags all data contained in that release with a release number (e.g. FB2008_10). If a release number was not used then a date stamp for when the entire genes data class was updated should be used. If this is not available or if individual genes are updated in a piecemeal fashion then a timestamp based on the query execution time should be used.

Result dates

The individual search results must provide a creation and last modified timestamp via the date_created and last_modified XML tags respectively. If this information is not available then the current timestamp at query execution should be used.

Return types

Each service may define its own return types. The client may request a specific return type by appending the appropriate file extension to the URL. If no file extension is appended then the default return type for that service is used.

Compression

Sending of compressed XML and JSON results should follow the same rules used for HTTP communication. If a client wishes to receive compressed output it should indicate this by setting the Accept-Encoding HTTP request header. When a service provider receives a request it should check for the Accept-Encoding request header and compress the output if it supports the requested compression algorithm. If the service provider does compress the content it should then set the Content-Encoding HTTP response header to indicate the compression algorithm used.

Supported HTTP methods

Currently this API only describes read only services that use the GET HTTP method. There are no plans to provide create, update or delete operations at this time.

Querying or Filtering by Organism

Some of the queries that have been defined below allow for querying and/or filtering by organism by using Taxonomy IDs from the NCBI's Taxonomy database (http://www.ncbi.nlm.nih.gov/Taxonomy/) or the genus and/or species name (e.g. 'Drosophila melanogaster'). Non-leaf taxons should be supported by the service provider. For example, if you want to query all species in the Sophophora submitting the taxon ID 32341 should allow you to perform such a query. In order to implement this service you can either implement your own methods or utilize the NCBI's elink application that is part of their Eutils service (e.g. http://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?id=32341&db=taxonomy&dbfrom=taxonomy)

Pretty URLs

In version 1.1 we have opted for a mixed approach of forming URLs that uses directory path structures to specify some elements and parameters to add additional filters.

Language Implementation Pages

GMOD_RPC_API/PHP

Error handling

HTTP error code 400

An HTTP 400 status code should be returned for the following errors.

not implemented - returned when a particular service is not implemented.
invalid term - returned when a particular CV term is not used by the service.

Use Cases

GMOD RPC API Use Cases

Services

Searches

Organism List

Service Name

organisms

Purpose

Provides a list of organisms that are able to be queried with the service provider.

URL

http://yourmod.org/gmodrpc/v<api version>/organisms[.xml | .json]

Return types

XML or JSON

Default return type

XML

Example URLs

http://flybase.org/gmodrpc/v1.1/organisms
http://flybase.org/gmodrpc/v1.1/organisms.xml
http://flybase.org/gmodrpc/v1.1/organisms.json

XML Result

<?xml version="1.0" encoding="UTF-8"?>
<resultset>
   <api_version>1.1</api_version>
   <data_provider>FlyBase</data_provider>
   <data_version>FB2008_10</data_version>
   <result>
      <organism>
         <genus>Drosophila</genus>
         <species>melanogaster</species>
         <taxonomy_id>7227</taxonomy_id>
      </organism>
   </result>
   <result>
      <organism>
          <species>Drosophila</species>
          <genus>simulans</genus>
          <taxonomy_id>7240</taxonomy_id>
      </organism>
    </result>
</resultset>

JSON Result

{
   resultset:{
       api_version:1.1,
       data_provider:'FlyBase',
       data_version:'FB2008_10',
       result:[
           {
               organism:{
                   genus:'Drosophila',
                   species:'melanogaster',
                   taxonomy_id:7227
               }
           },
           {
               organism:{
                   species:'Drosophila',
                   genus:'simulans',
                   taxonomy_id:7240
               }
           }
       ]
   }
}

Gene full text search

Service Name

fulltext

Purpose

Performs a full text search on records and returns the IDs for matching records.

Description

This service returns features that contain the search term anywhere in the gene record. Results can be restricted to a specific organism by supplying the NCBI taxonomy id.

URL

http://yourmod.org/gmodrpc/v<api version>/fulltext/<search term>[.xml | .json]?[type=<SO term ID>][taxid=<taxid>][genus=<genus>][species=<species>]

Return types

XML or JSON

Default return type

XML

Example URLs

http://flybase.org/gmodrpc/v1.1/fulltext/cotransfection?type=SO:0000704 - Find genes that contain the term cotransfection.
http://flybase.org/gmodrpc/v1.1/fulltext/cotransfection?type=SO:0000704&taxid=7227 - Find Drosophila melanogaster genes that contain the term cotransfection.
http://flybase.org/gmodrpc/v1.1/fulltext/AE003845.json?type=SO:0000704 - Find genes that contain the term AE003845 and return a JSON result.
http://flybase.org/gmodrpc/v1.1/fulltext/IPR000483.json?taxid=7240&type=SO:0000704 - Find Drosophila simulans genes that are labeled with InterPro ID IPR000483.

XML Result

<?xml version="1.0" encoding="UTF-8"?>
<resultset>
   <api_version>1.1</api_version>
   <data_provider>FlyBase</data_provider>
   <data_version>FB2008_10</data_version>
   <query_time>2009-01-15 09:03:00</query_time>
   <query_url>http://flybase.org/gmodrpc/v1.1/fulltext/cotransfection?type=SO:0000704</query_url>
   <result>
      <dbxref>
         <db>FlyBase</db>
         <accession>FBgn0085432</accession>
         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085432</url>
      </dbxref>
      <date_created>2003-03-08 00:00:00</date_created>
      <last_modified>2005-01-15 09:03:00</last_modified>
   </result>
   <result>
      <dbxref>
         <db>FlyBase</db>
         <accession>FBgn0004364</accession>
         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0004364</url>
      </dbxref>
      <date_created>2005-01-08 00:00:00</date_created>
      <last_modified>2009-01-01 00:00:00</last_modified>
   </result>
</resultset>

JSON Result

{
   resultset:{
       api_version:1.1,
       data_provider:'FlyBase',
       data_version:'FB2008_10',
       query_time:'2009-01-15 09:03:00',
       query_url:'http://flybase.org/gmodrpc/v1.1/fulltext/cotransfection?type=SO:0000704',
       result:[
           {
               dbxref:{
                   db:'FlyBase',
                   accession:'FBgn0085432',
                   url:'http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085432'
               },
               date_created:'2003-03-08 00:00:00',
               last_modified:'2005-01-15 09:03:00'
           },
           {
               dbxref:{
                   db:'FlyBase',
                   accession:'FBgn0004364',
                   url:'http://flybase.org/gmodrpc/v1.1/fetch/FBgn0004364'
               },
               date_created:'2005-01-08 00:00:00',
               last_modified:'2009-01-01 00:00:00'
           }
       ]
   }
}

Gene location

Service Name

location

Purpose

Retrieves a list of features that lie within a specific sequence range.

Description

This service returns features that lie within a specific sequence range. Arguments include the name of the largest assembled unit (i.e. chromosome, scaffold, etc...), location start (fmin), location stop (fmax), and strand. Results can be restricted to a specific organism by supplying the NCBI taxonomy id.

URL

http://yourmod.org/gmodrpc/v<api version>/location/chromosome/<name>[.xml | .json]?[type=<SO term ID>][fmin=<int>][fmax=<int>][strand=(1 | -1)][taxid=<taxid>][genus=<genus>][species=<species>]

Return types

XML or JSON

Default return type

XML

Example URLs

http://flybase.org/gmodrpc/v1.1/location/chromosome/X?type=SO:0000704 - Find all genes that are localized on the X chromosome of any Drosophila species.
http://flybase.org/gmodrpc/v1.1/location/chromosome/X?type=SO:0000704&taxid=7227 - Find all genes that are localized to the X chromosome of melanogaster.
http://flybase.org/gmodrpc/v1.1/location/chromosome/X.json?type=SO:0000704&fmin=40000&taxid=7227 - Find all genes that are localized on the X chromosome in the range of 40,000 bp to the end of X on any strand.
http://flybase.org/gmodrpc/v1.1/location/chromosome/X.xml?type=SO:0000704&genus=Drosophila&species=melanogaster&fmax=40000 - Find all genes that are localized on the X chromosome in the range of the start of the X up to and including 40,000 bp on any strand.
http://flybase.org/gmodrpc/v1.1/location/chromosome/X.xml?type=SO:0000704&fmin=50000&fmax=140000&strand=1&taxid=7227 - Find all genes that are localized on the plus strand of the X chromosome between and including 50,000 bp and 140,000 bp.

XML Result

<?xml version="1.0" encoding="UTF-8"?>
<resultset>
   <api_version>1.1</api_version>
   <data_provider>FlyBase</data_provider>
   <data_version>FB2008_10</data_version>
   <query_time>2009-01-15 09:03:00</query_time>
   <query_url>http://flybase.org/gmodrpc/v1.1/location/chromosome/2L?type=SO:0000704&amp;fmin=12587000&amp;fmax=12629000&amp;taxid=7227</query_url>
   <result>
      <dbxref>
         <db>FlyBase</db>
         <accession>FBgn0085424</accession>
         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085424</url>
      </dbxref>
      <date_created>2003-03-08 00:00:00</date_created>
      <last_modified>2005-01-15 09:03:00</last_modified>
   </result>
</resultset>

JSON Result

{
   resultset:{
       api_version:1.1,
       data_provider:'FlyBase',
       data_version:'FB2008_10',
       query_time:'2009-01-15 09:03:00',
       query_url:'http://flybase.org/gmodrpc/v1.1/location/chromosome/2L?type=SO:0000704&fmin=12587000&fmax=12629000&taxid=7227',
       result:[
           {
               dbxref:{
                   db:'FlyBase',
                   accession:'FBgn0085424',
                   url:'http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085424'
               },
               date_created:'2003-03-08 00:00:00',
               last_modified:'2005-01-15 09:03:00'
           }
       ]
   }
}

Gene Ontology search

Service Name

ontology

Purpose

Search for genes that have been annotated with a particular gene ontology ID.

Description

This service returns genes that have been annotated with a particular ontology term. Results can be restricted to a specific organism by supplying the NCBI taxonomy id.

URL

http://yourmod.org/gmodrpc/v<api version>/ontology/gene/<ontology ID>[.xml | .json]?[taxid=<taxid>][genus=<genus>][species=<species>]

Return types

XML or JSON

Default return type

XML

Example URLs

http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515 - Find all genes annotated with GO:0005515.
http://flybase.org/gmodrpc/v1.1/ontology/gene/!GO:0005515 - Find all genes annotated with GO:0005515 and the GO NOT operator.
http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515?taxid=7227 - Find all Drosophila melanogaster genes annotated with GO:0005515.
http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515.json - Find all genes annotated with GO:0005515 and return a JSON result.

XML Result

<?xml version="1.0" encoding="UTF-8"?>
<resultset>
   <api_version>1.1</api_version>
   <data_provider>FlyBase</data_provider>
   <data_version>FB2008_10</data_version>
   <query_time>2009-01-15 09:03:00</query_time>
   <query_url>http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515</query_url>
   <result>
      <dbxref>
         <db>FlyBase</db>
         <accession>FBgn0085432</accession>
         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085432</url>
      </dbxref>
      <date_created>2003-03-08 00:00:00</date_created>
      <last_modified>2005-01-15 09:03:00</last_modified>
   </result>
   <result>
      <dbxref>
         <db>FlyBase</db>
         <accession>FBgn0004364</accession>
         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0004364</url>
      </dbxref>
      <date_created>2005-01-08 00:00:00</date_created>
      <last_modified>2009-01-01 00:00:00</last_modified>
   </result>
</resultset>

JSON Result

{
   resultset:{
       api_version:1.1,
       data_provider:'FlyBase',
       data_version:'FB2008_10',
       query_time:'2009-01-15 09:03:00',
       query_url:'http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515',
       result:[
           {
               dbxref:{
                   db:'FlyBase',
                   accession:'FBgn0085432',
                   url:'http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085432'
               },
               date_created:'2003-03-08 00:00:00',
               last_modified:'2005-01-15 09:03:00'
           },
           {
               dbxref:{
                   db:'FlyBase',
                   accession:'FBgn0004364',
                   url:'http://flybase.org/gmodrpc/v1.1/fetch/FBgn0004364'
               },
               date_created:'2005-01-08 00:00:00',
               last_modified:'2009-01-01 00:00:00'
           }
       ]
   }
}

Gene ortholog search

Service name

orthologs/gene

Purpose

Search for orthologs of the supplied gene ID.

Description

This service returns genes that have been determined by some means to be orthologous to the supplied gene ID. If the supplied gene ID is within the namespace of the web service provider then all known orthologs of that gene are returned. If the supplied gene ID is not within the namespace of the web service provider then it only returns genes for organisms that are offered by the service provider.

For example, for a given gene FlyBase stores orthology calls to other FlyBase genes and non FlyBase genes. Thus, given a FlyBase gene ID you can obtain a list of gene IDs for genes within FlyBase and to other non Drosophila species. In addition, given a non FlyBase gene ID you can obtain a list of FlyBase genes that are orthologous to it.

Results can be restricted to a specific organism by supplying the NCBI taxonomy ID.

URL

http://yourmod.org/gmodrpc/v<api version>/orthologs/gene/<gene ID>[.xml | .json]?[taxid=<taxid>][genus=<genus>][species=<species>]

Return types

XML or JSON

Default return type

XML

Example URLs

http://flybase.org/gmodrpc/v1.1/orthologs/gene/FBgn0004364 - Find all FlyBase and non FlyBase genes that are orthologous to FBgn0004364.
http://flybase.org/gmodrpc/v1.1/orthologs/gene/FBgn0004364?taxid=7240 - Find out if FBgn0004364 has an ortholog in Drosophila simulans.
http://flybase.org/gmodrpc/v1.1/orthologs/gene/WBGene12345.json - Find all FlyBase genes that are orthologous to WBGene12345 and return a JSON result.

XML Result:

<?xml version="1.0" encoding="UTF-8"?>
<resultset>
   <api_version>1.1</api_version>
   <data_provider>FlyBase</data_provider>
   <data_version>FB2008_10</data_version>
   <query_time>2009-01-15 09:03:00</query_time>
   <query_url>http://flybase.org/gmodrpc/v1.1/orthologs/gene/FBgn0000490</query_url>
   <result>
      <dbxref>
         <db>FlyBase</db>
         <accession>FBgn0097591</accession>
         <data_provider>FlyBase</data_provider>
         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0097591</url>
      </dbxref>
   </result>
   <result>
      <dbxref>
          <db>ENSEMBL</db>
          <accession>ENSBTAP00000004992</accession>
          <data_provider>InParanoid</data_provider>
      </dbxref>
   </result>
</resultset>

JSON Result

{
   resultset:{
       api_version:1.1,
       data_provider:'FlyBase',
       data_version:'FB2008_10',
       query_time:'2009-01-15 09:03:00',
       query_url:'http://flybase.org/gmodrpc/v1.1/orthologs/gene/FBgn0000490',
       result:[
           {
               dbxref:{
                   db:'FlyBase',
                   accession:'FBgn0097591',
                   data_provider:'FlyBase'
                   url:'http://flybase.org/gmodrpc/v1.1/fetch/FBgn0097591'
               }
           },
           {
               dbxref:{
                   db:'ENSEMBL',
                   accession:'ENSBTAP00000004992',
                   data_provider:'InParanoid'
               }
           }
       ]
   }
}

Organism ortholog search

Service name

orthologs/organism

Purpose

Returns a list of orthologs between an organism and one or more other organisms.

Description

This service returns genes that have been determined by some means to be orthologous between a single organism and one or more other organisms. The organisms are specified by providing taxonomy IDs.

URL

http://yourmod.org/gmodrpc/v<api version>/orthologs/organism[/<taxid>][/genus/<genus>/species/<species>][.xml | .json]?[to_taxid=<taxid>][to_genus=<genus>&to_species=<species>]

Return types

XML or JSON

Default return type

XML

Example URLs

http://flybase.org/gmodrpc/v1.1/orthologs/organism/genus/Drosophila/species/melanogaster - Find all orthologs between Dmel and any other species.
http://flybase.org/gmodrpc/v1.1/orthologs/organism/7227.xml?to_taxid=7240 - Find all orthologs between Dmel and Dsim.
http://flybase.org/gmodrpc/v1.1/orthologs/organism/7227.json?to_taxid=7240 - Same as above except returned in JSON format.

XML Result:

<?xml version="1.0" encoding="UTF-8"?>
<resultset>
   <api_version>1.1</api_version>
   <data_provider>FlyBase</data_provider>
   <data_version>FB2008_10</data_version>
   <query_time>2009-01-15 09:03:00</query_time>
   <query_url>http://flybase.org/gmodrpc/v1.1/orthologs/organism/genus/Drosophila/species/melanogaster</query_url>
   <result>
      <dbxref>
         <db>FlyBase</db>
         <accession>FBgn0000490</accession>
         <taxonomy_id>7227</taxonomy_id>
         <data_provider>FlyBase</data_provider>
         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0000490</url>
      </dbxref>
      <dbxref>
         <db>FlyBase</db>
         <accession>FBgn0015673</accession>
         <taxonomy_id>7240</taxonomy_id>
         <data_provider>FlyBase</data_provider>
         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0015673</url>
      </dbxref>
      <dbxref>
         <db>WormBase</db>
         <accession>WBGene00006570</accession>
         <taxonomy_id>6239</taxonomy_id>
         <data_provider>InParanoid</data_provider>
         <url>http://wormbase.org/gmodrpc/v1.1/fetch/WBGene00006570</url>
      </dbxref>
   </result>
...
</resultset>

JSON Result

{
   resultset:{
       api_version:1.1,
       data_provider:'FlyBase',
       data_version:'FB2008_10',
       query_time:'2009-01-15 09:03:00',
       query_url:'http://flybase.org/gmodrpc/v1.1/orthologs/organism/genus/Drosophila/species/melanogaster',
       result:[
         {
           dbxref:[
               {
                   db:'FlyBase',
                   accession:'FBgn0000490',
                   taxonomy_id:7227,
                   data_provider:'FlyBase',
                   url:'http://flybase.org/gmodrpc/v1.1/fetch/FBgn0000490'
               },
               {
                   db:'FlyBase',
                   accession:'FBgn0015673'
                   taxonomy_id:7240,
                   data_provider:'FlyBase',
                   url:'http://flybase.org/gmodrpc/v1.1/fetch/FBgn0015673'
               },
               {
                   db:'WormBase',
                   accession:'WBGene00006570',
                   taxonomy_id:6239,
                   data_provider:'InParanoid',
                   url:'http://wormbase.org/gmodrpc/v1.1/fetch/WBGene00006570'
               }
           ]
         }
       ]
   }
}

Fetching

Gene records

Service name

fetch/gene

Purpose

To fetch gene records in the Generic gene page XML format as implemented by Bio GMOD GenericGenePage.

Description

URL

http://yourmod.org/gmodrpc/v<api version>/fetch/gene/<gene ID>

Return types

XML

Default return type

XML

Example URLs

http://flybase.org/gmodrpc/v1.1/fetch/gene/FBgn0097591

XML Result

See Bio GMOD GenericGenePage for example XML.

Sequence

Service name

fetch/seq

Purpose

Returns FASTA sequence for the specified query.

Description

URL

http://yourmod.org/gmodrpc/v<api version>/fetch/seq/<ID>[/<SO term ID of subtype>]

Return types

FASTA

Example URLs

http://flybase.org/gmodrpc/v1.1/fetch/seq/FBgn0097591.fasta - Fetch the FASTA sequence of FBgn0097591
http://flybase.org/gmodrpc/v1.1/fetch/seq/FBgn0097591/SO:0000204.fasta - Download all 5' UTRs of the gene FBgn0097591
http://flybase.org/gmodrpc/v1.1/fetch/seq/FBgn0097591/SO:0000316.fasta - Download all CDS features of the gene FBgn0097591
http://flybase.org/gmodrpc/v1.1/fetch/seq/FBgn0097591/SO:0000316.fasta - Download all CDS features of the gene FBgn0097591

FASTA Result:

TODO

WADLs for all services?

@@ Line 1: / Line 1: @@
-= Document Status =
+{{TocRight}}
+== Document Status ==
 In progress.
-= Background =
+== Background ==
-This effort was started after [[User:Jogoodma|Josh Goodman]]'s talk at the [[January 2009 GMOD Meeting]] meeting titled "MOD Web API (A RESTful interface for [[MOD]]s)".  The main idea is to increase interoperability among the various model organism databases by creating an easy to use high level RESTful API.  The queries iterated below are currently in the proposal stage and have no been implemented at any [[MOD]].
+This effort was started after [[User:Jogoodma|Josh Goodman]]'s talk at the [[January 2009 GMOD Meeting]] meeting titled "[[January 2009 GMOD Meeting#A RESTful Interface for MODs?|MOD Web API (A RESTful interface for MODs)]]".  The main idea is to increase interoperability among the various model organism databases by creating an easy to use high level RESTful [[Glossary#API|API]].  The queries iterated below are currently in the proposal stage and have no been implemented at any [[MOD]].
-= Members =
+== Members ==
 * [[User:Jogoodma|Josh Goodman]] - [http://flybase.org FlyBase]
-* Robert Buels - [http://www.sgn.cornell.edu/ SOL Genomics Network]
+* Robert Buels - [http://www.sgn.cornell.edu/ Sol Genomics Network]
+* Richard Smith - [http://www.intermine.org InterMine]
+* Giles Velarde - [http://www.genedb.org GeneDB]
+* [[User:Tharris|Todd Harris]] - [http://www.wormbase.org WormBase]
+* [[User:JimHu|Jim Hu]] - [http://ecoliwiki.net EcoliWiki]
+* [[User:alexkalderimis| Alex Kalderimis]] - [http://www.intermine.org InterMine]
 * ''Add your name here''
-= Goals =
+== Goals ==
 * Data model agnostic
-* Language agnostic
+* Programming language agnostic
 * Easy to use
 * Versioned URLs for API stability over time
-= Data classes =
+== Related projects ==
+* [[Common url]]
+* [[:Bio::GMOD]]
+* [[Bio GMOD GenericGenePage]]
+== Data classes ==
 At present, this API only covers querying and retrieving information for the gene data class.
-= API Version =
+== API Version ==
 In order to provide a stable URL API all web calls should be versioned according to what version of the GMOD REST API they are using.  The version number included in the URLs corresponds to the API version and not the data version.  As changes to the API are made the version number will be incremented.  Access to the older API versions should be provided indefinitely.
-'''Current GMOD REST API Version:''' 1
+'''Current GMOD REST API Version:''' 1.1
-= Data version =
+== Data version ==
-The search results must contain an XML tag called data_version that contains the database release number.  If the database does not use release numbers then the date for when the entire data class was updated should be used.  If that is not available or if individual records within a data class are updated and released asynchronously then a timestamp derived from the time of query execution should be used.
+The search results must contain an [[Glossary#XML|XML]] tag called data_version that contains the database release number.  If the database does not use release numbers then the date for when the entire data class was updated should be used.  If that is not available or if individual records within a data class are updated and released asynchronously then a timestamp derived from the time of query execution should be used.
-For example, [[FlyBase]] releases its data on a roughly monthly basis and tags all data contained in that release with a release number (e.g. FB2008_10).  If a release number was not used then a date stamp for when the entire genes data class was updated should be used.  If this is not available or if individual genes are updated in a piecemeal fashion then a timestamp based on the query execution time should be used.
+For example, [[:Category:FlyBase|FlyBase]] releases its data on a roughly monthly basis and tags all data contained in that release with a release number (e.g. FB2008_10).  If a release number was not used then a date stamp for when the entire genes data class was updated should be used.  If this is not available or if individual genes are updated in a piecemeal fashion then a timestamp based on the query execution time should be used.
-= Result dates =
+== Result dates ==
 The individual search results must provide a creation and last modified timestamp via the '''date_created''' and '''last_modified''' XML tags respectively.
 If this information is not available then the current timestamp at query execution should be used.
-= Return types =
+== Return types ==
 Each service may define its own return types.  The client may request a specific return type by appending the appropriate file extension to the URL.  If no file extension is appended then the default return type for that service is used.
-= Compression =
+== Compression ==
-Sending of compressed XML and JSON results should be dictated by the same rules used for HTTP communication.
+Sending of compressed XML and [[Glossary#JSON|JSON]] results should follow the same rules used for HTTP communication.  If a client wishes to receive compressed output it should indicate this by setting the Accept-Encoding HTTP request header.  When a service provider receives a request it should check for the Accept-Encoding request header and compress the output if it supports the requested compression algorithm.  If the service provider does compress the content it should then set the Content-Encoding HTTP response header to indicate the compression algorithm used.
-= Services =
+== Supported HTTP methods ==
-== Searches ==
+Currently this API only describes read only services that use the GET HTTP method.  There are no plans to provide create, update or delete operations at this time.
-=== Organism List ===
-==== Purpose ====
+== Querying or Filtering by Organism ==
+Some of the queries that have been defined below allow for querying and/or filtering by organism by using Taxonomy IDs
+from the NCBI's Taxonomy database (http://www.ncbi.nlm.nih.gov/Taxonomy/) or the genus and/or species name (e.g. 'Drosophila melanogaster').
+Non-leaf taxons should be supported by the service provider.  For example, if you want to query all species in the Sophophora submitting the
+taxon ID 32341 should allow you to perform such a query.  In order to implement this service you can either implement your own methods or
+utilize the NCBI's elink application that is part of their Eutils service
+(e.g. http://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?id=32341&db=taxonomy&dbfrom=taxonomy)
+== Pretty URLs ==
+In version 1.1 we have opted for a mixed approach of forming URLs that uses directory path structures to specify some elements and parameters to add additional
+filters.
+== Language Implementation Pages ==
+* [[GMOD_RPC_API/PHP]]
+== Error handling ==
+=== HTTP error code 400 ===
+An HTTP 400 status code should be returned for the following errors.
+* not implemented - returned when a particular service is not implemented.
+* invalid term - returned when a particular CV term is not used by the service.
+== Use Cases ==
+* [[GMOD RPC API Use Cases]]
+== Services ==
+=== Searches ===
+==== Organism List ====
+===== Service Name =====
+organisms
+===== Purpose =====
 Provides a list of organisms that are able to be queried with the service provider.
-==== URL ====
+===== URL =====
-<nowiki>http://yourmod.org/gmodrest/v<api version>/organisms[.xml | .json]</nowiki>
+<nowiki>http://yourmod.org/gmodrpc/v<api version>/organisms[.xml | .json]</nowiki>
-==== Return types ====
+===== Return types =====
 XML or JSON
-==== Default return type ====
+===== Default return type =====
 XML
-==== Example URLs ====
+===== Example URLs =====
-* <nowiki>http://flybase.org/gmodrest/v1/organisms</nowiki>
+* <nowiki>http://flybase.org/gmodrpc/v1.1/organisms</nowiki>
-* <nowiki>http://flybase.org/gmodrest/v1/organisms.xml</nowiki>
+* <nowiki>http://flybase.org/gmodrpc/v1.1/organisms.xml</nowiki>
-* <nowiki>http://flybase.org/gmodrest/v1/organisms.json</nowiki>
+* <nowiki>http://flybase.org/gmodrpc/v1.1/organisms.json</nowiki>
-==== XML Result ====
+===== XML Result =====
-<xml>
+<syntaxhighlight lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
 <resultset>
-    <api_version>1</api_version>
+    <api_version>1.1</api_version>
     <data_provider>FlyBase</data_provider>
     <data_version>FB2008_10</data_version>
-    <organism>
+    <result>
-       <genus>Drosophila</genus>
+      <organism>
-       <species>melanogaster</species>
+         <genus>Drosophila</genus>
-       <taxonomy_id>7227</taxonomy_id>
+         <species>melanogaster</species>
-   </organism>
+         <taxonomy_id>7227</taxonomy_id>
-    <organism>
+      </organism>
-       <species>Drosophila</species>
+    </result>
-       <genus>simulans</genus>
+   <result>
-       <taxonomy_id>7240</taxonomy_id>
+      <organism>
-   </organism>
+          <species>Drosophila</species>
+          <genus>simulans</genus>
+          <taxonomy_id>7240</taxonomy_id>
+      </organism>
+    </result>
 </resultset>
-</xml>
+</syntaxhighlight>
-==== JSON Result ====
+===== JSON Result =====
   {
      resultset:{
-         api_version:1,
+         api_version:1.1,
          data_provider:'FlyBase',
          data_version:'FB2008_10',
-         organism:[
+         result:[
              {
-                 genus:'Drosophila',
+                 organism:{
-                species:'melanogaster',
+                    genus:'Drosophila',
-                taxonomy_id:7227
+                    species:'melanogaster',
+                    taxonomy_id:7227
+                }
              },
              {
-                 species:'Drosophila',
+                 organism:{
-                genus:'simulans',
+                    species:'Drosophila',
-                taxonomy_id:7240
+                    genus:'simulans',
+                    taxonomy_id:7240
+                }
              }
          ]
@@ Line 104: / Line 155: @@
   }
-=== Gene full text search ===
+==== Gene full text search ====
-==== Purpose ====
+===== Service Name =====
-Performs a full text search on gene records and returns the IDs for matching reocrds.
+fulltext
-==== Description ====
+===== Purpose =====
-This service returns genes that contain the search term anywhere in the gene record.  Results
+Performs a full text search on records and returns the IDs for matching records.
+===== Description =====
+This service returns features that contain the search term anywhere in the gene record.  Results
 can be restricted to a specific organism by supplying the NCBI taxonomy id.
-==== URL====
+===== URL=====
-<nowiki>http://yourmod.org/gmodrest/v<api version>/fulltext/gene/<search term>[/organism/<taxonomy id>][.xml | .json]</nowiki>
+<nowiki>http://yourmod.org/gmodrpc/v<api version>/fulltext/<search term>[.xml | .json]?[type=<SO term ID>][taxid=<taxid>][genus=<genus>][species=<species>]</nowiki>
-==== Return types====
+===== Return types =====
 XML or JSON
-==== Default return type ====
+===== Default return type =====
 XML
-==== Example URLs ====
+===== Example URLs =====
-* <nowiki>http://flybase.org/gmodrest/v1/fulltext/gene/cotransfection</nowiki> - Find genes that contain the term cotransfection.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/fulltext/cotransfection?type=SO:0000704</nowiki> - Find genes that contain the term cotransfection.
-* <nowiki>http://flybase.org/gmodrest/v1/fulltext/gene/cotransfection/organism/7227</nowiki> - Find Drosophila melanogaster genes that contain the term cotransfection.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/fulltext/cotransfection?type=SO:0000704&taxid=7227</nowiki> - Find Drosophila melanogaster genes that contain the term cotransfection.
-* <nowiki>http://flybase.org/gmodrest/v1/fulltext/gene/AE003845.json</nowiki> - Find genes that contain the term AE003845 and return a JSON result.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/fulltext/AE003845.json?type=SO:0000704</nowiki> - Find genes that contain the term AE003845 and return a JSON result.
-* <nowiki>http://flybase.org/gmodrest/v1/fulltext/gene/IPR000483/organism/7240.json</nowiki> - Find Drosophila simulans genes that are labeled with InterPro ID IPR000483.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/fulltext/IPR000483.json?taxid=7240&type=SO:0000704</nowiki> - Find Drosophila simulans genes that are labeled with InterPro ID IPR000483.
-==== XML Result ====
+===== XML Result =====
-<xml>
+<syntaxhighlight lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
 <resultset>
-    <api_version>1</api_version>
+    <api_version>1.1</api_version>
     <data_provider>FlyBase</data_provider>
     <data_version>FB2008_10</data_version>
     <query_time>2009-01-15 09:03:00</query_time>
-    <query_url>http://flybase.org/gmodrest/v1/fulltext/gene/cotransfection</query_url>
+    <query_url>http://flybase.org/gmodrpc/v1.1/fulltext/cotransfection?type=SO:0000704</query_url>
     <result>
-       <id>FBgn0085432</id>
+       <dbxref>
+         <db>FlyBase</db>
+         <accession>FBgn0085432</accession>
+         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085432</url>
+      </dbxref>
        <date_created>2003-03-08 00:00:00</date_created>
        <last_modified>2005-01-15 09:03:00</last_modified>
     </result>
     <result>
-       <id>FBgn0004364</id>
+       <dbxref>
+         <db>FlyBase</db>
+         <accession>FBgn0004364</accession>
+         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0004364</url>
+      </dbxref>
        <date_created>2005-01-08 00:00:00</date_created>
        <last_modified>2009-01-01 00:00:00</last_modified>
     </result>
 </resultset>
-</xml>
+</syntaxhighlight>
-==== JSON Result ====
+===== JSON Result =====
   {
      resultset:{
-         api_version:1,
+         api_version:1.1,
          data_provider:'FlyBase',
          data_version:'FB2008_10',
          query_time:'2009-01-15 09:03:00',
-         query_url:'<nowiki>http://flybase.org/gmodrest/v1/fulltext/gene/cotransfection.json</nowiki>',
+         query_url:'<nowiki>http://flybase.org/gmodrpc/v1.1/fulltext/cotransfection?type=SO:0000704</nowiki>',
          result:[
              {
-                 id:'FBgn0085432',
+                 dbxref:{
+                    db:'FlyBase',
+                    accession:'FBgn0085432',
+                    url:'<nowiki>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085432</nowiki>'
+                },
                  date_created:'2003-03-08 00:00:00',
                  last_modified:'2005-01-15 09:03:00'
              },
              {
-                 id:'FBgn0004364',
+                 dbxref:{
+                    db:'FlyBase',
+                    accession:'FBgn0004364',
+                    url:'<nowiki>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0004364</nowiki>'
+                },
                  date_created:'2005-01-08 00:00:00',
                  last_modified:'2009-01-01 00:00:00'
@@ Line 172: / Line 242: @@
   }
-=== Gene ontology search ===
+==== Gene location ====
-==== Purpose ====
-Searches for genes that have a particular ontology ID.
-==== Description ====
+===== Service Name =====
+location
+===== Purpose =====
+Retrieves a list of features that lie within a specific sequence range.
+===== Description =====
+This service returns features that lie within a specific sequence range.  Arguments include the name of
+the largest assembled unit (i.e. chromosome, scaffold, etc...), location start (fmin), location stop
+(fmax), and strand.  Results can be restricted to a specific organism by supplying the NCBI taxonomy id.
+===== URL=====
+<nowiki>http://yourmod.org/gmodrpc/v<api version>/location/chromosome/<name>[.xml | .json]?[type=<SO term ID>][fmin=<int>][fmax=<int>][strand=(1 | -1)][taxid=<taxid>][genus=<genus>][species=<species>]</nowiki>
+===== Return types =====
+XML or JSON
+===== Default return type =====
+XML
+===== Example URLs =====
+* <nowiki>http://flybase.org/gmodrpc/v1.1/location/chromosome/X?type=SO:0000704</nowiki> - Find all genes that are localized on the X chromosome of any Drosophila species.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/location/chromosome/X?type=SO:0000704&taxid=7227</nowiki> - Find all genes that are localized to the X chromosome of melanogaster.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/location/chromosome/X.json?type=SO:0000704&fmin=40000&taxid=7227</nowiki> - Find all genes that are localized on the X chromosome in the range of 40,000 bp to the end of X on any strand.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/location/chromosome/X.xml?type=SO:0000704&genus=Drosophila&species=melanogaster&fmax=40000</nowiki> - Find all genes that are localized on the X chromosome in the range of the start of the X up to and including 40,000 bp on any strand.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/location/chromosome/X.xml?type=SO:0000704&fmin=50000&fmax=140000&strand=1&taxid=7227</nowiki> - Find all genes that are localized on the plus strand of the X chromosome between and including 50,000 bp and 140,000 bp.
+===== XML Result =====
+<syntaxhighlight lang="xml">
+<?xml version="1.0" encoding="UTF-8"?>
+<resultset>
+   <api_version>1.1</api_version>
+   <data_provider>FlyBase</data_provider>
+   <data_version>FB2008_10</data_version>
+   <query_time>2009-01-15 09:03:00</query_time>
+   <query_url>http://flybase.org/gmodrpc/v1.1/location/chromosome/2L?type=SO:0000704&amp;fmin=12587000&amp;fmax=12629000&amp;taxid=7227</query_url>
+   <result>
+      <dbxref>
+         <db>FlyBase</db>
+         <accession>FBgn0085424</accession>
+         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085424</url>
+      </dbxref>
+      <date_created>2003-03-08 00:00:00</date_created>
+      <last_modified>2005-01-15 09:03:00</last_modified>
+   </result>
+</resultset>
+</syntaxhighlight>
+===== JSON Result =====
+ {
+    resultset:{
+        api_version:1.1,
+        data_provider:'FlyBase',
+        data_version:'FB2008_10',
+        query_time:'2009-01-15 09:03:00',
+        query_url:'<nowiki>http://flybase.org/gmodrpc/v1.1/location/chromosome/2L?type=SO:0000704&fmin=12587000&fmax=12629000&taxid=7227</nowiki>',
+        result:[
+            {
+                dbxref:{
+                    db:'FlyBase',
+                    accession:'FBgn0085424',
+                    url:'<nowiki>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085424</nowiki>'
+                },
+                date_created:'2003-03-08 00:00:00',
+                last_modified:'2005-01-15 09:03:00'
+            }
+        ]
+    }
+ }
+==== Gene Ontology search ====
+===== Service Name =====
+ontology
+===== Purpose =====
+Search for genes that have been annotated with a particular gene ontology ID.
+===== Description =====
 This service returns genes that have been annotated with a particular ontology term.  Results
 can be restricted to a specific organism by supplying the NCBI taxonomy id.
-==== URL ====
+===== URL =====
-<nowiki>http://yourmod.org/gmodrest/v<api version>/ontology/gene/<ontology ID>[/organism/<taxonomy id>][.xml | .json]</nowiki>
+<nowiki>http://yourmod.org/gmodrpc/v<api version>/ontology/gene/<ontology ID>[.xml | .json]?[taxid=<taxid>][genus=<genus>][species=<species>]</nowiki>
-==== Return types ====
+===== Return types =====
 XML or JSON
-==== Default return type ====
+===== Default return type =====
 XML
-==== Example URLs ====
+===== Example URLs =====
-* <nowiki>http://flybase.org/gmodrest/v1/ontology/gene/GO:12345</nowiki> - Find all genes annotated with GO:12345.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515</nowiki> - Find all genes annotated with GO:0005515.
-* <nowiki>http://flybase.org/gmodrest/v1/ontology/gene/GO:12345/organism/7227</nowiki> - Find all Drosophila melanogaster genes annotated with GO:12345.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/ontology/gene/!GO:0005515</nowiki> - Find all genes annotated with GO:0005515 and the GO NOT operator.
-* <nowiki>http://flybase.org/gmodrest/v1/ontology/gene/GO:12345.json</nowiki> - Find all genes annotated with GO:12345 and return a JSON result.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515?taxid=7227</nowiki> - Find all Drosophila melanogaster genes annotated with GO:0005515.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515.json</nowiki> - Find all genes annotated with GO:0005515 and return a JSON result.
-==== XML Result ====
+===== XML Result =====
-<xml>
+<syntaxhighlight lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
 <resultset>
-    <api_version>1</api_version>
+    <api_version>1.1</api_version>
     <data_provider>FlyBase</data_provider>
     <data_version>FB2008_10</data_version>
     <query_time>2009-01-15 09:03:00</query_time>
-    <query_url>http://flybase.org/gmodrest/v1/ontology/gene/GO:12345</query_url>
+    <query_url>http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515</query_url>
     <result>
-       <id>FBgn0085432</id>
+       <dbxref>
+         <db>FlyBase</db>
+         <accession>FBgn0085432</accession>
+         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085432</url>
+      </dbxref>
        <date_created>2003-03-08 00:00:00</date_created>
        <last_modified>2005-01-15 09:03:00</last_modified>
     </result>
     <result>
-       <id>FBgn0004364</id>
+       <dbxref>
+         <db>FlyBase</db>
+         <accession>FBgn0004364</accession>
+         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0004364</url>
+      </dbxref>
        <date_created>2005-01-08 00:00:00</date_created>
        <last_modified>2009-01-01 00:00:00</last_modified>
     </result>
 </resultset>
-</xml>
+</syntaxhighlight>
-==== JSON Result ====
+===== JSON Result =====
   {
      resultset:{
-         api_version:1,
+         api_version:1.1,
          data_provider:'FlyBase',
          data_version:'FB2008_10',
          query_time:'2009-01-15 09:03:00',
-         query_url:'<nowiki>http://flybase.org/gmodrest/v1/ontology/gene/GO:12345.json</nowiki>',
+         query_url:'<nowiki>http://flybase.org/gmodrpc/v1.1/ontology/gene/GO:0005515</nowiki>',
          result:[
              {
-                 id:'FBgn0085432',
+                 dbxref:{
+                    db:'FlyBase',
+                    accession:'FBgn0085432',
+                    url:'<nowiki>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0085432</nowiki>'
+                },
                  date_created:'2003-03-08 00:00:00',
                  last_modified:'2005-01-15 09:03:00'
              },
              {
-                 id:'FBgn0004364',
+                 dbxref:{
+                    db:'FlyBase',
+                    accession:'FBgn0004364',
+                    url:'<nowiki>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0004364</nowiki>'
+                },
                  date_created:'2005-01-08 00:00:00',
                  last_modified:'2009-01-01 00:00:00'
@@ Line 239: / Line 401: @@
   }
-=== Gene ortholog search ===
+==== Gene ortholog search ====
-==== Purpose ====
+===== Service name =====
+orthologs/gene
+===== Purpose =====
 Search for orthologs of the supplied gene ID.
-==== Description ====
+===== Description =====
 This service returns genes that have been determined by some means to be orthologous
 to the supplied gene ID.  If the supplied gene ID is within the namespace of the web service provider
@@ Line 255: / Line 420: @@
 FlyBase genes that are orthologous to it.
-Results can be restricted to a specific organism by supplying the NCBI taxonomy id.
+Results can be restricted to a specific organism by supplying the NCBI taxonomy ID.
-==== URL ====
+===== URL =====
-<nowiki>http://yourmod.org/gmodrest/v<api version>/ortholog/gene/<gene ID>[/organism/<taxonomy id>][.xml | .json]</nowiki>
+<nowiki>http://yourmod.org/gmodrpc/v<api version>/orthologs/gene/<gene ID>[.xml | .json]?[taxid=<taxid>][genus=<genus>][species=<species>]</nowiki>
-==== Return types ====
+===== Return types =====
 XML or JSON
-==== Default return type ====
+===== Default return type =====
 XML
-==== Example URLs ====
+===== Example URLs =====
-* <nowiki>http://flybase.org/gmodrest/v1/ortholog/gene/FBgn0004364</nowiki> - Find all FlyBase and non FlyBase genes that are orthologous to FBgn0004364.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/orthologs/gene/FBgn0004364</nowiki> - Find all FlyBase and non FlyBase genes that are orthologous to FBgn0004364.
-* <nowiki>http://flybase.org/gmodrest/v1/ortholog/gene/FBgn0004364/organism/7240</nowiki> - Find out if FBgn0004364 has an ortholog in Drosophila simulans.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/orthologs/gene/FBgn0004364?taxid=7240</nowiki> - Find out if FBgn0004364 has an ortholog in Drosophila simulans.
-* <nowiki>http://flybase.org/gmodrest/v1/ortholog/gene/WBGene12345.json</nowiki> - Find all FlyBase genes that are orthologous to WBGene12345 and return a JSON result.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/orthologs/gene/WBGene12345.json</nowiki> - Find all FlyBase genes that are orthologous to WBGene12345 and return a JSON result.
-==== XML Result: ====
+===== XML Result: =====
-<xml>
+<syntaxhighlight lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
 <resultset>
-    <api_version>1</api_version>
+    <api_version>1.1</api_version>
     <data_provider>FlyBase</data_provider>
     <data_version>FB2008_10</data_version>
     <query_time>2009-01-15 09:03:00</query_time>
-    <query_url>http://flybase.org/gmodrest/v1/ortholog/gene/FBgn0000490</query_url>
+    <query_url>http://flybase.org/gmodrpc/v1.1/orthologs/gene/FBgn0000490</query_url>
     <result>
-       <id>FBgn0097591</id>
+       <dbxref>
-      <date_created>2003-03-08 00:00:00</date_created>
+         <db>FlyBase</db>
-      <last_modified>2005-01-15 09:03:00</last_modified>
+         <accession>FBgn0097591</accession>
+         <data_provider>FlyBase</data_provider>
+         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0097591</url>
+      </dbxref>
     </result>
     <result>
-       <id>ENSBTAP00000004992</id>
+       <dbxref>
-      <date_created>2005-01-08 00:00:00</date_created>
+          <db>ENSEMBL</db>
-      <last_modified>2009-01-01 00:00:00</last_modified>
+          <accession>ENSBTAP00000004992</accession>
+          <data_provider>InParanoid</data_provider>
+      </dbxref>
     </result>
 </resultset>
-</xml>
+</syntaxhighlight>
-==== JSON Result ====
+===== JSON Result =====
   {
      resultset:{
-         api_version:1,
+         api_version:1.1,
          data_provider:'FlyBase',
          data_version:'FB2008_10',
          query_time:'2009-01-15 09:03:00',
-         query_url:'<nowiki>http://flybase.org/gmodrest/v1/ortholog/gene/FBgn0000490.json</nowiki>',
+         query_url:'<nowiki>http://flybase.org/gmodrpc/v1.1/orthologs/gene/FBgn0000490</nowiki>',
          result:[
              {
-                 id:'FBgn0097591',
+                 dbxref:{
-                date_created:'2003-03-08 00:00:00',
+                    db:'FlyBase',
-                last_modified:'2005-01-15 09:03:00'
+                    accession:'FBgn0097591',
+                    data_provider:'FlyBase'
+                    url:'<nowiki>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0097591</nowiki>'
+                }
              },
              {
-                 id:'ENSBTAP00000004992',
+                 dbxref:{
-                date_created:'2005-01-08 00:00:00',
+                    db:'ENSEMBL',
-                last_modified:'2009-01-01 00:00:00'
+                    accession:'ENSBTAP00000004992',
+                    data_provider:'InParanoid'
+                }
              }
          ]
@@ Line 316: / Line 491: @@
   }
+==== Organism ortholog search ====
+===== Service name =====
+orthologs/organism
+===== Purpose =====
+Returns a list of orthologs between an organism and one or more other organisms.
+===== Description =====
+This service returns genes that have been determined by some means to be orthologous
+between a single organism and one or more other organisms.  The organisms are specified by providing taxonomy IDs.
+===== URL =====
+<nowiki>http://yourmod.org/gmodrpc/v<api version>/orthologs/organism[/<taxid>][/genus/<genus>/species/<species>][.xml | .json]?[to_taxid=<taxid>][to_genus=<genus>&to_species=<species>]</nowiki>
+===== Return types =====
+XML or JSON
+===== Default return type =====
+XML
+===== Example URLs =====
+* <nowiki>http://flybase.org/gmodrpc/v1.1/orthologs/organism/genus/Drosophila/species/melanogaster</nowiki> - Find all orthologs between Dmel and any other species.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/orthologs/organism/7227.xml?to_taxid=7240</nowiki> - Find all orthologs between Dmel and Dsim.
+* <nowiki>http://flybase.org/gmodrpc/v1.1/orthologs/organism/7227.json?to_taxid=7240</nowiki> - Same as above except returned in JSON format.
+===== XML Result: =====
+<syntaxhighlight lang="xml">
+<?xml version="1.0" encoding="UTF-8"?>
+<resultset>
+   <api_version>1.1</api_version>
+   <data_provider>FlyBase</data_provider>
+   <data_version>FB2008_10</data_version>
+   <query_time>2009-01-15 09:03:00</query_time>
+   <query_url>http://flybase.org/gmodrpc/v1.1/orthologs/organism/genus/Drosophila/species/melanogaster</query_url>
+   <result>
+      <dbxref>
+         <db>FlyBase</db>
+         <accession>FBgn0000490</accession>
+         <taxonomy_id>7227</taxonomy_id>
+         <data_provider>FlyBase</data_provider>
+         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0000490</url>
+      </dbxref>
+      <dbxref>
+         <db>FlyBase</db>
+         <accession>FBgn0015673</accession>
+         <taxonomy_id>7240</taxonomy_id>
+         <data_provider>FlyBase</data_provider>
+         <url>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0015673</url>
+      </dbxref>
+      <dbxref>
+         <db>WormBase</db>
+         <accession>WBGene00006570</accession>
+         <taxonomy_id>6239</taxonomy_id>
+         <data_provider>InParanoid</data_provider>
+         <url>http://wormbase.org/gmodrpc/v1.1/fetch/WBGene00006570</url>
+      </dbxref>
+   </result>
+...
+</resultset>
+</syntaxhighlight>
+===== JSON Result =====
+ {
+    resultset:{
+        api_version:1.1,
+        data_provider:'FlyBase',
+        data_version:'FB2008_10',
+        query_time:'2009-01-15 09:03:00',
+        query_url:'<nowiki>http://flybase.org/gmodrpc/v1.1/orthologs/organism/genus/Drosophila/species/melanogaster</nowiki>',
+        result:[
+          {
+            dbxref:[
+                {
+                    db:'FlyBase',
+                    accession:'FBgn0000490',
+                    taxonomy_id:7227,
+                    data_provider:'FlyBase',
+                    url:'<nowiki>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0000490</nowiki>'
+                },
+                {
+                    db:'FlyBase',
+                    accession:'FBgn0015673'
+                    taxonomy_id:7240,
+                    data_provider:'FlyBase',
+                    url:'<nowiki>http://flybase.org/gmodrpc/v1.1/fetch/FBgn0015673</nowiki>'
+                },
+                {
+                    db:'WormBase',
+                    accession:'WBGene00006570',
+                    taxonomy_id:6239,
+                    data_provider:'InParanoid',
+                    url:'<nowiki>http://wormbase.org/gmodrpc/v1.1/fetch/WBGene00006570</nowiki>'
+                }
+            ]
+          }
+        ]
+    }
+ }
+=== Fetching ===
+==== Gene records ====
+===== Service name =====
+fetch/gene
+===== Purpose =====
+To fetch gene records in the Generic gene page XML format as implemented by [[Bio GMOD GenericGenePage]].
+===== Description =====
+===== URL =====
+<nowiki>http://yourmod.org/gmodrpc/v<api version>/fetch/gene/<gene ID></nowiki>
+===== Return types =====
+XML
+===== Default return type =====
+XML
+===== Example URLs =====
+* <nowiki>http://flybase.org/gmodrpc/v1.1/fetch/gene/FBgn0097591</nowiki>
+===== XML Result =====
+See [[Bio GMOD GenericGenePage]] for example XML.
+==== Sequence ====
+===== Service name =====
+fetch/seq
+===== Purpose =====
+Returns FASTA sequence for the specified query.
+===== Description =====
+===== URL =====
+<nowiki>http://yourmod.org/gmodrpc/v<api version>/fetch/seq/<ID>[/<SO term ID of subtype>]</nowiki>
+===== Return types =====
+FASTA
+===== Example URLs =====
+* <nowiki>http://flybase.org/gmodrpc/v1.1/fetch/seq/FBgn0097591.fasta</nowiki> - Fetch the FASTA sequence of FBgn0097591
+* <nowiki>http://flybase.org/gmodrpc/v1.1/fetch/seq/FBgn0097591/SO:0000204.fasta</nowiki> - Download all 5' UTRs of the gene FBgn0097591
+* <nowiki>http://flybase.org/gmodrpc/v1.1/fetch/seq/FBgn0097591/SO:0000316.fasta</nowiki> - Download all CDS features of the gene FBgn0097591
+* <nowiki>http://flybase.org/gmodrpc/v1.1/fetch/seq/FBgn0097591/SO:0000316.fasta</nowiki> - Download all CDS features of the gene FBgn0097591
+===== FASTA Result: =====
-== Fetching ==
-= TODO =
+== TODO ==
-* Should we use the NCBI eUtils XML formats?
+* WADLs for all services?
-* Write schemas for the XML formats.
-* Double check REST compliance.
-* Do we need additional fields for full text result format (organism, etc...)?
-* Specify a timestamp format.
-* Add more details on HTTP headers required to use compression.
-* Add ability to use multiple search and ontology terms in one query and perform basic logical operations (AND, OR, NOT).
-* Add support for GO's NOT operator.
-* Need a null result format.
 [[Category:REST]]
-[[Category: Web services]]
+[[Category:Web services]]
+[[Category:RPC]]

Difference between revisions of "GMOD RPC API"

Latest revision as of 23:02, 15 August 2013

Contents

Document Status

Background

Members

Goals

Related projects

Data classes

API Version

Data version

Result dates

Return types

Compression

Supported HTTP methods

Querying or Filtering by Organism

Pretty URLs

Language Implementation Pages

Error handling

HTTP error code 400

Use Cases

Services

Searches

Organism List

Service Name

Purpose

URL

Return types

Default return type

Example URLs

XML Result

JSON Result

Gene full text search

Service Name

Purpose

Description

URL

Return types

Default return type

Example URLs

XML Result

JSON Result

Gene location

Service Name

Purpose

Description

URL

Return types

Default return type

Example URLs

XML Result

JSON Result

Gene Ontology search

Service Name

Purpose

Description

URL

Return types

Default return type

Example URLs

XML Result

JSON Result

Gene ortholog search

Service name

Purpose

Description

URL

Return types

Default return type

Example URLs

XML Result:

JSON Result

Organism ortholog search

Service name

Purpose

Description

URL

Return types

Default return type

Example URLs