TogoWS: References

Integration of the bioinformatics web services

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

TogoWS リソース

これまでに開発された TogoWS 関連リソースです。

TogoWS では SOAP/WSDL によるプロキシーサービスと REST によるエントリ取得機能（BioRuby を利用したパーザ内蔵）を提供しています。

バージョン: 1.2 (2008/10/28)

統合ウェブサービスマニフェスト

以下、ウェブサービスを提供するにあたり、容易に統合可能なサービスを開発するための指針をマニフェストとして提案します。

REST サービス全般

データベース系のサービス提供においては REST での検索とエントリの取得を可能とすること（URL へのマッピングについては TogoWS のガイドラインに準拠）
クエリを統一するため、検索キーワードの書式は Common Query Language に準拠すること
検索キーワードからヒット件数が取得できること
検索キーワードからヒットしたエントリの ID のリストが取得できること
エントリの ID から実際のエントリが取得可能であること
エントリが無かった場合 HTTP レスポンスコード 404 (Not Found) と空のエントリを返すこと
サーバ側でサービスの処理中にエラーが発生した場合、HTTP レスポンスコード 505 (Internal Server Error) を返すこと
REST の URL にはパス変数 (/foo/bar/baz) を用い、クエリ変数 (param1=value1&param2=value2....) は使用しない
- パス変数には原則として小文字を使用する
- URL が / で終わっている場合、原則としてスラッシュの後に続けることのできる文字列のリストを返す
リストを返す場合は、エントリ単位で改行し、エントリ内はタブ区切りとする

SOAP サービス全般

メソッド毎にマニュアルを書くこと
パラメータについて、ちゃんと動く値の例を示すこと
少なくとも Java, Perl, Ruby, Python での動作確認を行うこと
サンプルコードが提供されればベター
非同期サービスはジョブIDを発行する
サーバ側で処理中にエラーが発生した場合は SOAP Fault を返す

戻り値の型を可能な限り統一すること

配列 INSDC
発現 MIAMI
糖鎖 GLYDE-II
配列アノテーション GFF
key - value ペアタブ区切り

REST にするか SOAP にするか

データベースエントリの検索や取得については容易に URL にマッピング可能なので REST で提供することが望ましい。それ以外の解析サービスや実行時間のかかるサービス、さまざまな引数を必要とするサービスを提供する場合は SOAP を用いるとよい。

TogoWS ガイドライン

REST サービス

TogoWS では、以下のルールでエントリの取得や検索を URL にマッピングしました。

	http://togows.dbcls.jp/site/services.html
	http://togows.dbcls.jp/site/rest.html

エントリの取得

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

URL のホスト部にデータベース名などの名前空間が含まれる場合：

	http://frnadb.example.org/entry/frnadb/id の代わりに  http://frnadb.example.org/entry/id とする

データベースに組織等の名前空間やバージョン番号を含めたい場合：

	http://togows.dbcls.jp/entry/birc-hinv-5.0/HIT0012345

戻り値について：

基本的には、デフォルトはテキストフォーマットのエントリを返すが、フォーマットを指定したい場合は .xml など拡張子をつけることで指定する。

エントリの部分要素取得について：

エントリの一部を field 名で取得できる機能は BioRuby/BioPerl を利用した TogoWS の拡張ですが、バックエンドが XML データベースの場合など、field の代わりに XPath を利用することも検討可能。

エントリの検索

検索文字列 "query string" の書式は Common Query Language のサブセットを使用する。結果の order については現時点では未定義。

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

データ形式や ID の変換

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

メタデータ

対応DB一覧

	http://togows.dbcls.jp/entry/
	http://togows.dbcls.jp/search/

対応フィールド名一覧

	http://togows.dbcls.jp/entry/DB名/

対応フォーマット一覧（エントリIDの一覧は取得できないので代わりに）

	http://togows.dbcls.jp/entry/DB名/formats

SOAP サービス

少なくとも以下の環境での動作確認を行う

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 バージョンは 1.2 に準拠するのが望ましい

現状のサービスの SOAP, WSDL バージョンを調査して検討
REST も包括するという噂の 2.0 も検討する

WSDL ファイル作製の際は以下の点に注意する

targetNamespaces 属性は URL を指定する - Java の WSDL2Java の制限を避けるため
Any 型を使用しない - Ruby, Python で対応できないため
名前空間のプレフィックスに soap という文字列を使用しない - SOAP::Lite などで対応できないため
メソッドのパラメータの名前に org という文字列を使用しない - Java で対応できないため

非同期メソッドについて

レスポンスに 30 秒以上かかるサービスは非同期サービスとして提供する
非同期サービスでは以下の３つのメソッドを提供する
サービスを実行するためのメソッド：非同期メソッド名は Async で終わり、ジョブ ID を返す
メソッドの実行状況を問い合わせるメソッド： CheckAsyncStatus メソッドにジョブ ID を渡し、RUNNING, COMPLETED, ERROR のいずれかの文字列を返す
サービスの実行結果を取得するメソッド：非同期メソッドの実行結果を取得するためのメソッド名は「非同期メソッド名＋Result」とし、引数にジョブ ID を渡す

複合型をクエリにしたサービスの利用が困難となるため、複雑な複合型の使用は極力避ける

複合型のなかに複合型を含める場合、最大でも３階層までにする（１階層を推奨）
Hash 型、GFF 型などシンプルかつ汎用的なデータ型の使用を検討する
複雑な複合型を戻り値とせざるを得ない場合は、複合型から値を取り出すためのライブラリを提供することが望ましい

Ruby, Python などのライブラリでサポートされていないため Attachement (MIME binding) は使用しない

Attachement の API を提供する場合は、Attachement 専用の WSDL ファイルを用意し、１つの WSDL ファイル中に Attachement の API と Attachement ではない API を共存させない

Python などのライブラリでサポートされていないため、ステートフルなサービス実装の手段として Cookie を用いない

Perl もデフォルトでは非対応、Ruby でも利用するためにはクライアント側でコーディングが必要となる

SOAP レスポンスのデータにおいて、データの種類を表す場合、SOAP レスポンス (XML) の属性でデータの種類を表すのではなく、要素名でデータの種類を表現する

複合型において、NCBI のように XML のタグ名は Item に統一し属性に name="title" などと表現した場合、属性の取れない Perl などのライブラリで使用できないため（Ruby, Python でも対応は難しい）

巨大なデータを返すサービスは REST で提供するのが望ましい