Revision as of 18:37, 17 January 2009

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
• Add your name here

Goals

• Data model agnostic
• Language agnostic
• Easy to use
• Versioned URLs for API stability over time

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

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.

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 be dictated by the same rules used for HTTP communication.

Services

Searches

Organism List

Purpose: Obtain a list of organisms that are able to be queried with the service provider.
URL: http://yourmod.org/gmodrest/v<api version>/organisms[.xml | .json]
Return types: XML or JSON
Default return type: XML
Example URLs:

• http://flybase.org/gmodrest/v1/organisms.xml
• http://flybase.org/gmodrest/v1/organisms.json

XML Result: <xml> <?xml version="1.0" encoding="UTF-8"?> <resultset>

  <api_version>1</api_version>
  <data_provider>FlyBase</data_provider>
  <data_version>FB2008_10</data_version>
  <organism>
      <genus>Drosophila</genus>
      <species>melanogaster</species>
      <taxonomy_id>7227</taxonomy_id>
  </organism>
  <organism>
      <species>Drosophila</species>
      <genus>simulans</genus>
      <taxonomy_id>7240</taxonomy_id>
  </organism>

</resultset> </xml> JSON Result:

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

Gene full text search

Purpose: Obtain a list of IDs that match a gene full text query.
URL: http://yourmod.org/gmodrest/v<api version>/fulltext/gene/<search term>[+<search term>][/species/<species>][/genus/<genus>][.xml | .json]
Return types: XML or JSON
Default return type: XML
Example URLs:

• http://flybase.org/gmodrest/v1/fulltext/gene/cotransfection
• http://flybase.org/gmodrest/v1/fulltext/gene/cotransfection/species/drosophila/genus/melanogaster
• http://flybase.org/gmodrest/v1/fulltext/gene/AE003845.json
• http://flybase.org/gmodrest/v1/fulltext/gene/IPR000483/species/drosophila/genus/simulans.json
• http://flybase.org/gmodrest/v1/fulltext/gene/egg+expression.xml

XML Result: <xml> <?xml version="1.0" encoding="UTF-8"?> <resultset>

  <api_version>1</api_version>
  <data_provider>FlyBase</data_provider>
  <data_version>FB2008_10</data_version>
  <result>
     <id>FBgn0085432</id>
     <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>
     <date_created>2005-01-08 00:00:00</date_created>
     <last_modified>2009-01-01 00:00:00</last_modified>
  </result>

</resultset> </xml> JSON Result:

{
   resultset:{
       api_version:1,
       data_provider:'FlyBase',
       data_version:'FB2008_10',
       result:[
           {
               id:'FBgn0085432',
               date_created:'2003-03-08 00:00:00',
               last_modified:'2005-01-15 09:03:00'
           },
           {
               id:'FBgn0004364',
               date_created:'2005-01-08 00:00:00',
               last_modified:'2009-01-01 00:00:00'
           }
       ]
   }

}

Fetching

TODO

• Should we use the NCBI eUtils XML formats?
• Write schemas for the XML formats.
• Double check REST compliance.
• Do we need additional fields for full text result format?
• Timestamp format?
• Add more details on HTTP headers required to use compression.