Version 28 (modified by atsuko, 15 years ago)

--

Guideline for Web Services

This document is a guideline to design web services toward integration.

  • REST
    • For a database service, REST services to call entries and search by a keyword should be provided.
    • To unify query formats, the query languages should conform to Common Query Language.
    • A method to get the number of hits for a keyword should be provided.
    • A method to get the list of hit entries for a keyword should be provided.
    • A method to get the entry from an ID should be provided.
      • If the entry does not exist, the method should return code 404 and an empty entry.
    • Path parameters (/foo/bar/baz) should be used for a REST URL and query parameters (param1=value1&param2=value2) should not be used.
      • Lower-case letters should be used for path parameters in principle.
      • If a URL ends "/", a list of possible strings after the URL should be returned in principle.
    • When a method return a list, each line should correspond to an entry and each field should be divided by tab.
  • SOAP
    • A manual for each method should be prepared.
      • The manual should include an example of parameters such that the method works well by them.
    • Each method should be verified to use Java, Perl, Ruby and Python.
      • Providing sample codes for such languages is recommended.
    • For asynchronous services, a job ID should be provided.
    • When any error occurs during processing at a server, a method should return "SOAP Fault".
  • The following types should be used:
    • INSDC for sequences,
    • MIAMI for expression data,
    • GLYDE-II for glycans,
    • tab format for key-value.
  • REST or SOAP
    • For a method to get an entry or search entries by keyword, REST is recommended. For a method of analysis service, SOAP is recommended.

TogoWS TogoWS Guidelines

REST

TogoWS stated the rulers as below:

How to call the entries

http://togows.dbcls.jp/entry/database/entry_id[,entry_id2,...]/field[.format]

If the name space of the databases are in URL:

How to add the name spaces for the institution, release_numer of the database:

NOTE: The default fotmat for the entries is “.txt”, and can be in the specified format by adding the suffix, such as “.xml”.

Calling a part of the entry: The method to call the part of the entries by field names is the extension of TogoWS using BioRuby/BioPerl?

How to search the entries

http://togows.dbcls.jp/search/database/query+string[.format][/offset,limit[.format]] 
http://togows.dbcls.jp/search/database/query+string/count

The format of "query string" to be based on “Common Query Language"  Common Query Language

The conversion of data format and ID

http://togows.dbcls.jp/convert/data_source.format

Metadata

  • The list of the databases
http://togows.dbcls.jp/entry/
http://togows.dbcls.jp/search/
  • The list of the fields
http://togows.dbcls.jp/entry/DBname/
  • The list of the formats
http://togows.dbcls.jp/entry/DBname/formats

SOAP

  • Required test environment
    • Perl: Soap::Lite 0.69
    • Ruby: SOAP4R 1.5.5 (Ruby 1.8.6 bundle)
    • Python: SOAPpy 0.12.0
    • Java: Axis 1.4
  • SOAP version 1.2, at least
  • Calling a method with asynchronous
    • The name for the method with asynchronous end with “Async” and return job ID
    • Rerurn job ID to “CheckAsyncStatus??” method and give either RUNNING, COMPLETED, or ERROR
    • Method name for the method with asynchronous mst be” BeginInvoke? methods+Result” and stae job ID as a parameter

History