Specification of the OReFiL WebAPI for obtaining online resource information

SOAP Interface
REST Interface
Responses
SOAP Request / Response Sample
REST Request / Response Sample

Comments and suggestions are welcome, please send an email to yayamamo AT cb DOT k DOT u-tokyo DOT ac DOT jp.

Interface Specifications

SOAP

WSDL
- /online_resource/service.wsdl
Entry Point
- /online_resource/api
SOAPAction
- /online_resource/api/GetResourceInfoById
Parameters

Name	Description	Must/Optional	Default Value	Allowable Values
id	Online resource ID	Must	-	Integer

Errors
- Follows the SOAP error specification as much as possible.

REST

URI
- /online_resource/< id >.xml
  - Specifying an online resource id at < id >
Errors
- Basically users need to handle errors based on HTTP statuses.
- The error description is given in an XML format as much as possible if there is an error in user parameters.
  - Error description
    - errors: a list of errors
      - error: description of each error
        http_status_code: HTTP status code
        code: application error code
        name: error name
        message: error message
  - Error sample
```
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>
    <http_status_code>401</http_status_code>
    <code>40401</code>
    <name>Orefil::InvalidOnlineResourceId</name>
    <message>Entry not Found. (:id => 99999)</message>
  </error>
</errors>
```

Response

return (OnlineResource): Online resource ( online_resource if REST )
- id: Online resource ID
- title: Title of the online resource
- updated_at: Update time ( XML Schema format )
- average_stars: Average rating
- mesh_term_list: A list of MeSH terms
  - item: A MeSH term ( mesh_term if REST )
- url: Online resource's URL
- related_resources: Related Resources
  - item: Related Resource's urls ( `url` if REST )
- pages: A list of URLs that search for referring links
  - item: Referring link search ( `page` if REST )
    - name: Name of the search engine
    - url: URL for search
- papers: A list of URLs that search for citing papers
  - item: Citing paper search ( `paper` if REST )
    - name: Name of the search engine
    - url: URL for search
- pmid_list: A ilst of PMIDs that cite the resource
  - item: pmid ( pmid if REST )

Request / Response Sample

Here are samples of requests and their corresponding responses in SOAP and REST.

Request
- Online resource ID : 4980

SOAP

Request

<?xml version="1.0" encoding="UTF-8"?>

  <SOAP-ENV:Envelope

    xmlns:xsd="http://www.w3.org/2001/XMLSchema"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"

    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

      <SOAP-ENV:Body>

        <m:GetResourceInfoById xmlns:m="urn:ActionWebService">

          <id xsi:type="xsd:int">4980</id>

        </m:GetResourceInfoById>

      </SOAP-ENV:Body>

    </SOAP-ENV:Envelope>

Response

<?xml version="1.0" encoding="UTF-8" ?>
<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Body>
    <n1:GetResourceInfoByIdResponse xmlns:n1="urn:ActionWebService"
        env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <return xsi:type="n1:Resource..OnlineResource">
        <url xsi:type="xsd:string">http://genome.ucsc.edu/</url>
        <updated_at xsi:type="xsd:dateTime">2008-02-20T00:00:00+09:00</updated_at>
        <pmid_list n2:arrayType="xsd:string[15]"
            xmlns:n2="http://schemas.xmlsoap.org/soap/encoding/"
            xsi:type="n2:Array">
          <item>16888352</item>
          <item>16381938</item>
          <item>12045153</item>
          <item>15216554</item>
          <item>17151077</item>
          <item>16888348</item>
          <item>16372332</item>
          <item>11932250</item>
          <item>16722777</item>
          <item>12519945</item>
          <item>16500937</item>
          <item>17142222</item>
          <item>15554057</item>
          <item>15608236</item>
          <item>16888346</item>
        </pmid_list>
        <mesh_term_list xmlns:n3="http://schemas.xmlsoap.org/soap/encoding/"
            xsi:type="n3:Array"
            n3:arrayType="xsd:string[28]">
          <item>Abnormalities, Multiple</item>
          <item>Carbamoyl-Phosphate Synthase I Deficiency Disease</item>
          <item>Chickens</item>
          <item>Chromosome Deletion</item>
          <item>Chromosome Mapping</item>
          <item>Chromosomes, Human, Pair 2</item>
          <item>Computational Biology</item>
          <item>DNA Primers</item>
          <item>Database Management Systems</item>
          <item>Databases, Genetic</item>
          <item>Databases, Nucleic Acid</item>
          <item>Databases, Protein</item>
          <item>Exons</item>
          <item>Genome</item>
          <item>Genome, Human</item>
          <item>Genomics</item>
          <item>Information Storage and Retrieval</item>
          <item>Internet</item>
          <item>Linkage (Genetics)</item>
          <item>Microsatellite Repeats</item>
          <item>Polymorphism, Single Nucleotide</item>
          <item>Proteins</item>
          <item>Proteome</item>
          <item>Proteomics</item>
          <item>RNA, Messenger</item>
          <item>Sequence Alignment</item>
          <item>Software</item>
          <item>Zebrafish</item>
        </mesh_term_list>
        <title xsi:type="xsd:string">UCSC Genome Browser Home</title>
        <papers n4:arrayType="n1:Resource..Paper[4]"
            xmlns:n4="http://schemas.xmlsoap.org/soap/encoding/"
            xsi:type="n4:Array">
          <item>
            <url xsi:type="xsd:string">http://www.biomedcentral.com/search/results.asp?txtSearch1=http%3A%2F%2Fgenome.ucsc.edu%2F&amp;chkBMCJournals=true&amp;chkCurrentOpinion=true&amp;drpFromDate=&amp;drpToDate=&amp;chkNSP=true&amp;drpAddedInLast=&amp;drpOrderBy=by+date&amp;drpPerPage=20&amp;drpAbstract=no+abstract&amp;strTempString=&amp;strSearchBoxType=bmc_boolean_results&amp;Search.x=10&amp;jou_id=&amp;Search.x=0&amp;Search.y=0&amp;Search=Search</url>
            <name xsi:type="xsd:string">BioMed Central</name>
          </item>
          <item>
            <url xsi:type="xsd:string">http://www.scirus.com/srsapp/search?q=http%3A%2F%2Fgenome.ucsc.edu%2F&amp;ds=jnl&amp;g=s&amp;t=all</url>
            <name xsi:type="xsd:string">Scirus</name>
          </item>
          <item>
            <url xsi:type="xsd:string">http://highwire.org/cgi/searchresults?fulltext=http%3A%2F%2Fgenome.ucsc.edu%2F</url>
            <name xsi:type="xsd:string">HighWire Press</name>
          </item>
          <item>
            <url xsi:type="xsd:string">http://scholar.google.com/scholar?hl=en&amp;lr=&amp;q=http%3A%2F%2Fgenome.ucsc.edu%2F&amp;btnG=Search</url>
            <name xsi:type="xsd:string">Google Scholar</name>
          </item>
        </papers>
        <pages n5:arrayType="n1:Resource..Page[2]"
            xmlns:n5="http://schemas.xmlsoap.org/soap/encoding/"
            xsi:type="n5:Array">
          <item>
            <url xsi:type="xsd:string">http://www.google.com/search?hl=en&amp;q=link%3ahttp%3A%2F%2Fgenome.ucsc.edu%2F&amp;btnG=Google+Search</url>
            <name xsi:type="xsd:string">Google</name>
          </item>
          <item>
            <url xsi:type="xsd:string">http://siteexplorer.search.yahoo.com/search?p=http%3A%2F%2Fgenome.ucsc.edu%2F</url>
            <name xsi:type="xsd:string">Yahoo</name>
          </item>
        </pages>
        <average_stars xsi:type="xsd:double">+3.285714285714286</average_stars>
        <id xsi:type="xsd:int">4980</id>
        <related_resources n6:arrayType="xsd:string[2]"
            xmlns:n6="http://schemas.xmlsoap.org/soap/encoding/"
            xsi:type="n6:Array">
          <item>http://example.com/resource1</item>
          <item>http://noicondomain.com/resource1</item>
        </related_resources>
      </return>
    </n1:GetResourceInfoByIdResponse>
  </env:Body>
</env:Envelope>

REST

Request
```
/online_resource/4980.xml
```

Response

<?xml version="1.0" encoding="UTF-8"?>
<online_resource>
  <id>4980</id>
  <title>UCSC Genome Browser Home</title>
  <updated_at>2008-02-20T00:00:00+09:00</updated_at>
  <average_stars>3.28571428571429</average_stars>
  <mesh_term_list>
    <mesh_term>Abnormalities, Multiple</mesh_term>
    <mesh_term>Carbamoyl-Phosphate Synthase I Deficiency Disease</mesh_term>
    <mesh_term>Chickens</mesh_term>
    <mesh_term>Chromosome Deletion</mesh_term>
    <mesh_term>Chromosome Mapping</mesh_term>
    <mesh_term>Chromosomes, Human, Pair 2</mesh_term>
    <mesh_term>Computational Biology</mesh_term>
    <mesh_term>DNA Primers</mesh_term>
    <mesh_term>Database Management Systems</mesh_term>
    <mesh_term>Databases, Genetic</mesh_term>
    <mesh_term>Databases, Nucleic Acid</mesh_term>
    <mesh_term>Databases, Protein</mesh_term>
    <mesh_term>Exons</mesh_term>
    <mesh_term>Genome</mesh_term>
    <mesh_term>Genome, Human</mesh_term>
    <mesh_term>Genomics</mesh_term>
    <mesh_term>Information Storage and Retrieval</mesh_term>
    <mesh_term>Internet</mesh_term>
    <mesh_term>Linkage (Genetics)</mesh_term>
    <mesh_term>Microsatellite Repeats</mesh_term>
    <mesh_term>Polymorphism, Single Nucleotide</mesh_term>
    <mesh_term>Proteins</mesh_term>
    <mesh_term>Proteome</mesh_term>
    <mesh_term>Proteomics</mesh_term>
    <mesh_term>RNA, Messenger</mesh_term>
    <mesh_term>Sequence Alignment</mesh_term>
    <mesh_term>Software</mesh_term>
    <mesh_term>Zebrafish</mesh_term>
  </mesh_term_list>
  <url>http://genome.ucsc.edu/</url>
  <related_resources>
    <url>http://example.com/resource1</url>
    <url>http://noicondomain.com/resource1</url>
  </related_resources>
  <pages>
    <page>
      <name>Google</name>
      <url>
        http://www.google.com/search?hl=en&amp;q=link%3ahttp%3A%2F%2Fgenome.ucsc.edu%2F&amp;btnG=Google+Search
      </url>
    </page>
    <page>
      <name>Yahoo</name>
      <url>
        http://siteexplorer.search.yahoo.com/search?p=http%3A%2F%2Fgenome.ucsc.edu%2F
      </url>
    </page>
  </pages>
  <papers>
    <paper>
      <name>BioMed Central</name>
      <url>
        http://www.biomedcentral.com/search/results.asp?txtSearch1=http%3A%2F%2Fgenome.ucsc.edu%2F&amp;chkBMCJournals=true&amp;chkCurrentOpinion=true&amp;drpFromDate=&amp;drpToDate=&amp;chkNSP=true&amp;drpAddedInLast=&amp;drpOrderBy=by+date&amp;drpPerPage=20&amp;drpAbstract=no+abstract&amp;strTempString=&amp;strSearchBoxType=bmc_boolean_results&amp;Search.x=10&amp;jou_id=&amp;Search.x=0&amp;Search.y=0&amp;Search=Search
      </url>
    </paper>
    <paper>
      <name>Scirus</name>
      <url>
        http://www.scirus.com/srsapp/search?q=http%3A%2F%2Fgenome.ucsc.edu%2F&amp;ds=jnl&amp;g=s&amp;t=all
      </url>
    </paper>
    <paper>
      <name>HighWire Press</name>
      <url>
        http://highwire.org/cgi/searchresults?fulltext=http%3A%2F%2Fgenome.ucsc.edu%2F
      </url>
    </paper>
    <paper>
      <name>Google Scholar</name>
      <url>
        http://scholar.google.com/scholar?hl=en&amp;lr=&amp;q=http%3A%2F%2Fgenome.ucsc.edu%2F&amp;btnG=Search
      </url>
    </paper>
  </papers>
  <pmid_list>
    <pmid>16888352</pmid>
    <pmid>16381938</pmid>
    <pmid>12045153</pmid>
    <pmid>15216554</pmid>
    <pmid>17151077</pmid>
    <pmid>16888348</pmid>
    <pmid>16372332</pmid>
    <pmid>11932250</pmid>
    <pmid>16722777</pmid>
    <pmid>12519945</pmid>
    <pmid>16500937</pmid>
    <pmid>17142222</pmid>
    <pmid>15554057</pmid>
    <pmid>15608236</pmid>
    <pmid>16888346</pmid>
  </pmid_list>
</online_resource>