読者です 読者をやめる 読者になる 読者になる

Drafts

@cm3 の草稿置場 / 少々Wikiっぽく使っているので中身は適宜追記修正されます。

Open API Initiative による RESTful APIの記述標準化

RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに - Publickey で紹介されているように、Open API Initiativeが立ち上がって、Swaggerの2.0をベースに RESTful API の記述標準化が始まった。まだ openapis.org に仕様は書かれておらず、Swagger 見てね、という状態。

RESTful API が何かはだいたい分かっているものとして、それを標準化するというのはどういうことか、何が便利になるのか。


まず、API を作る側のドキュメンテーション作業が楽になる。

などで紹介されているように、Swagger は jsonyamlAPI の仕様を書くことでHTMLのドキュメンテーションが自動化できるようになっている。

例えば、

のような json を Swagger で読み込むと

のようなページが作成され、そこで様々なAPIコールを試したりもできるようになっている。

API を作る側のドキュメンテーション作業が楽になるということは、使う側が得られるドキュメンテーションのクオリティが平均的に高くなるということも意味する。現在、このような API コールを試したりできる説明ページを提供している API は多くない。


そして、この仕様を記述する jsonSpecification | Swagger のページに書かれているように記述フォーマットが定められている。現段階では、名だたる大企業が、このフォーマットを標準化のベースにしますというお墨付きを与えたということになる。

json というデータフォーマットで記述するため言語に非依存で書けるが、それぞれの言語ごとにライブラリでサポートされていたりする。より正確に言えば、言語ごとというより、ウェブフレームワークのようなレベルでサポートされていたりする。言語が nodejs ならば Node.js - swagger-expressを使って簡単にAPIドキュメントを作成する - Qiita で紹介されているようにウェブフレームワークである express 用のライブラリが提供されている。結局プログラムのコメントに yaml で書き込んだり、プログラム内にjsonで値を定義したりしている場合が多いので、あまり労力は変わっていないのだが、コードのメンテ上の利便性の面では API のコードとドキュメンテーションを対応付けて書いておいた方が良いかもしれない。

サーバアプリで既存の使用例としては、データ管理のプラットフォーム Girder で使えるようになっていて、kitware.com上のデモでその動きを確認できる。

参考: