Guideline for Web Services

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

• REST
  • For a database service, REST services to get entries and search by a keyword should be provided.
  • To unify a format of a query, a query language 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 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 better.
  • For non-synchronous services, a job ID should be provided.
  • When any error occurs during processing at a server, a method

• TogoWS Guidelines

REST

TogoWS stated the rulers below: •  http://togows.dbcls.jp/site/services.html •  http://togows.dbcls.jp/site/rest.html • How to call the entries

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

# How to include the name space of the databases in URL： •  http://frnadb.example.org/entry/id instead of  http://frnadb.example.org/entry/frnadb/id # How to add the name spaces for the institution, release_numer of the database: •  http://togows.dbcls.jp/entry/birc-hinv-5.0/HIT0012345 NOTE: The default fotmat for the entries is “.txt”, and can be in the specified format by adding the suffix, such as “.xml”. 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“

The conversion and data format and ID  http://togows.dbcls.jp/convert/data_source.format Metadata • The list of the databases  http://togows.dbcls.jp/entry/ • The list of the fields  http://togows.dbcls.jp/entry/DB名/ • The list of the formats  http://togows.dbcls.jp/entry/DB_name/formats SOAP • Calling a method with asynchronous o The name for the method with asynchronous end with “Async” and return job ID o Rerurn job ID to “CheckAsyncStatus??” method and give either RUNNING, COMPLETED, or ERROR o Method name for the method with asynchronous mst be” BeginInvoke? methods＋Result” and stae job ID as a parameter • Required test environment o Perl: Soap::Lite 0.69 o Ruby: SOAP4R 1.5.5 (Ruby 1.8.6 bundle) o Python: SOAPpy 0.12.0 o Java: Axis 1.4