DDBJ WebAPI (wabi)再興

WABI : Web API for Biology

REST
Representational State Transfer(REST) は、ウェブのような分散ハイパーメディアシステムのためのソフトウェアアーキテクチャのスタイルのひとつである. この語は2000年に、HTTPプロトコル規格の主要著者の一人であるRoy Fieldingが、ウェブについて書いた博士論文で初めて現れ、ネットワーキングコミュニティの中ですぐに広く使われることになった. http://ja.wikipedia.org/wiki/REST

Roy Fieldingの博士論文 "Architectural Styles and the Design of Network-based Software Architectures"

RESTfulアーキテクチャの原則 (Bill Burke, RESTful Java with JAX-RS, O'Reilly 2009) 解説 : winplusの日記 RESTへどうぞ
 * 1) Addressable resources
 * 2) * すべてのリソースはURIで到達可能でなければならない.
 * 3) A uniform, constrained interface
 * 4) * リソースを操作するためには、よく定義されたメソッドの小さな１セットを利用しなさい.
 * 5) * RESTではURIには「アクション」パラメータを指定せず、WebサービスにはHTTPのメソッドのみを使用するということになる. HTTPのメソッドである、GET,PUT,DELETE,POST,HEAD,OPTIONS等を使って「アクション」を表現する.
 * 6) Representation-oriented
 * 7) * ひとつのURIによって参照されるリソースには複数の表現が存在する場合がある. たとえば、ブラウザはHTMLを、JavaScriptはJSONを、JavaアプリケーションはXMLを必要とするかもしれない.
 * 8) Communicate statelessly
 * 9) * ステートレスなアプリケーションは、簡単にスケールする.
 * 10) Hypermedia As The Engine Of Application State; HATEOAS
 * 11) * （WebAPIが返す）データ中に遷移先を書くやり方、を使ってよし.

問題は2.A uniform, constrained interface. RESTってGETメソッドだけで所望の情報が得られるwebサービスのことではないのでした. この本では複雑な「アクション」はPOSTで送るデータの中に書くものだ、と主張しています.

Javaの規格
 * List Of All JSRs : http://jcp.org/en/jsr/all
 * JSR224 : JAX-WS 2.0 (SOAP) : http://jcp.org/en/jsr/detail?id=224
 * JSR311 : JAX-RS (REST) : http://jcp.org/en/jsr/detail?id=311
 * http://jersey.java.net/ Jersey is the open source, production quality, JAX-RS (JSR 311) Reference Implementation for building RESTful Web services.

サーブレットはHTTPプロトコルと非常に近い関係にあり、HITP リクエストへの情報の出し入れにはたくさんの決まりきったコードが必要になる. そこで2008 年、RESTfulサービス実装を簡素化するためにJAX-RS と呼ばれる新しい仕様が定義された. (Bill Burke, RESTful Java with JAX-RS, O'Reilly 2009)

Java EE フレームワークとして広く使われている Spring では、RESTful な Web サービスを作成するためのサポートがリリース 3 で追加されました. Spring 3 での REST サポートは JAX-RS の実装ではありませんが、JAX-RS の仕様で定義されている以上の機能を持っています. この REST サポートは Spring の MVC レイヤーにシームレスに統合されており、Spring を使って作成されるアプリケーションの中に容易に取り入れることができます. http://www.ibm.com/developerworks/jp/web/library/wa-spring3webserv/

いろいろなwebAPI (生物関係)

 * NCBI Entrez Programming Utilities
 * Entrez Programming Utilities (E-utilities) Help ( http://www.ncbi.nlm.nih.gov/books/NBK25501/ )
 * The Entrez Programming Utilities (E-utilities) are a set of eight server-side programs that provide a stable interface into the Entrez query and database system at the National Center for Biotechnology Information (NCBI).
 * NCBI Entrez Utilities Web Service ( http://www.ncbi.nlm.nih.gov/entrez/query/static/esoap_help.html )
 * The NCBI Entrez Utilities Web Service enables developers to access Entrez Programming Utilities (E-utilities) via the Simple Object Access Protocol (SOAP).
 * E-utilitiesにSOAPのインタフェイスをつけたものを別に用意した、ということ. Java (Apache Axis2 version 1.4.1)等を使用.


 * DBCLS TogoWS　http://togows.dbcls.jp/
 * RESTとSOAP両方
 * /か?db=..かの違いを抜きにすると、E-utilitiesと作りが良く似ています.

URL体系比較

 * NCBI E-utilities
 * http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=science[journal]+AND+breast+cancer+AND+2008[pdat]
 * http://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=protein&id=6678417,9507199,28558982,28558984,28558988,28558990
 * togoWS
 * http://togows.dbcls.jp/entry/database/entry_id[,entry_id2,...]/field[.format]
 * http://togows.dbcls.jp/search/database/query+string[.format][/offset,limit[.format]]
 * http://togows.dbcls.jp/convert/data_source.format
 * DDBJ WABI
 * http://xml.nig.ac.jp/rest/Invoke?service=ServiceName&method=MethodName&param=...

厳密にRESTになっているかについてそんなに固いことを言わなくてもいいのだが、作法通りに作ればユーザーは使い方を理解しやすいだろう. 新しく作るならなるべく作法どおりに作りたいものだ.

WABI (2009)の仕様のまとめ
[http://nar.oxfordjournals.org/content/37/suppl_2/W11.full Nucl. Acids Res. (2009) 37 (suppl 2): W11-W16. doi: 10.1093/nar/gkp300]


 * wabi Cookbook http://wabi.ddbj.nig.ac.jp/CookBook_jp/index.php/%E3%83%A1%E3%82%A4%E3%83%B3%E3%83%9A%E3%83%BC%E3%82%B8


 * WABI (REST) ARSAの仕様 (2009)
 * WABI (REST) BLASTの仕様 (2009)
 * WABI (REST) ClustalWの仕様 (2009)
 * WABI (REST) DDBJの仕様 (2009)
 * WABI (REST) EnsEMBLの仕様 (2009)
 * WABI (REST) GetEntryの仕様 (2009)
 * WABI (REST) GIBの仕様 (2009)
 * WABI (REST) GIBISの仕様 (2009)
 * WABI (REST) GIB-Vの仕様 (2009)
 * WABI (REST) GTOPの仕様 (2009)
 * WABI (REST) GTPSの仕様 (2009)
 * WABI (REST) MAFFTの仕様 (2009)
 * WABI (REST) NCBI GenomeAnnotationの仕様 (2009)
 * WABI (REST) PhylogenicTreeの仕様 (2009)
 * WABI (REST) RequestManagerの仕様 (2009)
 * WABI (REST) SPSの仕様 (2009)
 * WABI (REST) TxSearchの仕様 (2009)
 * WABI (REST) VecScreenの仕様 (2009)

仕様（案） : URLの整理
RESTが主張している原則はURIは「物」を指すと言うことです. 結果としてURIの最後は物のIDになります. （呼び出すと実際に物が返ってくる --- すなわちサーバー上の物の在処をさしている --- のでここではURI,URLの区別はとりあえずどうでもよい. ）

WABIの対象にはblast, clustalwのような「プログラム」とDDBJのリリースデータやNCBI taxnomyといった「データベース」があります.

プログラムの場合
プログラムの場合、以下のようなURLで指される「物」はJobと考える. http://ddbj.nig.ac.jp/wabi/blast/{request-id}

この考え方で行くと呼び出し方は以下のようになります. GET   http://ddbj.nig.ac.jp/wabi/blast/{id}  : requestIdで表されるjobの現在の状況を報告する POST  http://ddbj.nig.ac.jp/wabi/blast       : jobの投入. requestIDを発行する. PUT   http://ddbj.nig.ac.jp/wabi/blast/{id}  : jobの再投入. 以前POSTしたものと同じ条件でjobを投入する. UGEのjobIDは内部で変わるがrequestIDは同じ. DELETE http://wabi.ddbj.nig.ac.jp/wabi/blast/{id} : jobの停止 --- 後回し. （認証等が要る） (OPTIONS, HEAD, TRACE --- 実装しない)

GETについては以下のようになる. GET blast/{id}?info=status    : jobが走っている、キューにたまっている、終わっている、存在しない、ということを返す. GET blast/{id}?info=result    : jobが終わっていたら結果を返す. 終わってない・存在しない場合は、エラーを返す. GET blast/{id}?info=request   : プログラム実行条件を返す. 存在しない場合は、エラーを返す.

データベースの場合
データベースの場合、以下のようなURLで指される「物」はデータベースのエントリである. http://www.ddbj.nig.ac.jp/wabi/DDBJ_release/{accession}

この考え方で行くと、DBの更新や削除はないので、結果としてGET,POSTメソッド以外は要りません. GET DDBJ_release/{accession}                         : エントリが返る. GET DDBJ_release/{accession}?info="history"          : 過去の変更履歴 (デフォルトはinfo="entry"とすればよい) GET DDBJ_release/{accession}?revisionID="revisionID" : 過去のエントリ POST DDBJ_release                                    : 全文検索? --- Solrを直接呼べばよいので今は作成せず. (GET DDBJ_release?query="your query terms"           : 全文検索??）


 * DDBJ_releaseなんて名前でいいのか？WGSとかリリースではないからそこはWGSになるのか？
 * 単にDDBJだと建物とか組織の名前に見えますが. DDBJってデータベースの名前なの？

プログラム・データベース共通
返すフォーマット GET DDBJ_release/{accession}?format="xml" : 結果のフォーマットを指定する. html, xml, json, plain-textなど.

BLASTの場合
以下のパラメーターをPOSTする.

job投入時のパラメーターファイルの例
WABI BLASTを利用するクライアントプログラムを作成してjobを投入する場合、POSTするパラメーターを記述したファイルを作成し、これをクライアントプログラムに読ませて内容をHTTPパラメーターとしてPOSTすることが多いと思われる.

このパラメーターファイルをJSON形式で作成すると、以下のようになる.

{ "querySequence": ">test1\r\nacgtacgtacgtacgtacgtacgt\r\n>test2\r\nacgcacgatgtacgtagctacgatcgta", "program": "blastn", "datasets": "", "database": "hum", "parameters": "-v 100 -b 100 -e 10 -F F -W 1", "result": "www", "address": "" }

ただし、querySequenceパラメーターは別途fasta形式のファイルを用意し、これをクライアントプログラムに読ませてquerySequenceパラメーターの値を生成し、POSTする方が取り回しが楽であろう.

クライアントプログラムの例
以下に、querySequenceをtest.fastaから、WABIのURL、test.fastaの場所、その他のパラメータ値をconf.jsonから読み出し、WABIにデータをPOSTしてBLAST検索結果を取得するクライアントプログラムの例を挙げる.

wabi-client.pl

conf.json { "urlStr": "http://ddbj.nig.ac.jp/wabi/blast/", "fasta": "~/test.fasta", "program": "blastn", "database": "hum", "parameters": "-v 100 -b 100 -e 10 -F F -W 11", "datasets": "", "result": "www", "address": "" }

test.fasta >test_seq ATGGCAAGCATGGCTGCCGTGCTCACCTGGGCTCTGGCTCTTCTTTCAGCGTTTTCGGCCACCCAGGCAC GGAAAGGCTTCTGGGACTACTTCAGCCAGACCAGCGGGGACAAAGGCAGGGTGGAGCAGATCCATCAGCA GAAGATGGCTCGCGAGCCCGCGACCCTGAAAGACAGCCTTGAGCAAGACCTCAACAATATGAACAAGTTC CTGGAAAAGCTGAGGCCTCTGAGTGGGAGCGAGGCTCCTCGGCTCCCACAGGACCCGGTGGGCATGCGGC GGCAGCTGCAGGAGGAGTTGGAGGAGGTGAAGGCTCGCCTCCAGCCCTACATGGCAGAGGCGCACGAGCT GGTGGGCTGGAATTTGGAGGGCTTGCGGCAGCAACTGAAGCCCTACACGATGGATCTGATGGAGCAGGTG GCCCTGCGCGTGCAGGAGCTGCAGGAGCAGTTGCGCGTGGTGGGGGAAGACACCAAGGCCCAGTTGCTGG GGGGCGTGGACGAGGCTTGGGCTTTGCTGCAGGGACTGCAGAGCCGCGTGGTGCACCACACCGGCCGCTT CAAAGAGCTCTTCCACCCATACGCCGAGAGCCTGGTGAGCGGCATCGGGCGCCACGTGCAGGAGCTGCAC CGCAGTGTGGCTCCGCACGCCCCCGCCAGCCCCGCGCGCCTCAGTCGCTGCGTGCAGGTGCTCTCCCGGA AGCTCACGCTCAAGGCCAAGGCCCTGCACGCACGCATCCAGCAGAACCTGGACCAGCTGCGCGAAGAGCT CAGCAGAGCCTTTGCAGGCACTGGGACTGAGGAAGGGGCCGGCCCGGACCCCCAGATGCTCTCCGAGGAG GTGCGCCAGCGACTTCAGGCTTTCCGCCAGGACACCTACCTGCAGATAGCTGCCTTCACTCGCGCCATCG ACCAGGAGACTGAGGAGGTCCAGCAGCAGCTGGCGCCACCTCCACCAGGCCACAGTGCCTTCGCCCCAGA GTTTCAACAAACAGACAGTGGCAAGGTTCTGAGCAAGCTGCAGGCCCGTCTGGATGACCTGTGGGAAGAC ATCACTCACAGCCTTCATGACCAGGGCCACAGCCATCTGGGGGACCCCTGA