岩本隆史の日記帳（アーカイブ）

はてなダイアリーのサービス終了をうけて移行したものです。更新はしません。

RESTクライアントが知っているべきこと

REST Webアプリ

クライアントとサーバの密結合を避けられるのが、RESTスタイルに従って得られるメリットのひとつです。クライアントが、アプリケーションの挙動に関する知識をほとんど持たなくてよいわけです。

とはいっても、まったく何も知らないではクライアントたりえません。では、何を知っていればよいのでしょうか。

知っているべき4点

その答えは、Roy T. Fielding による記事「REST APIs must be hypertext-driven」で、すでに示されています。下記の4つです。

  • 通信プロトコル（communication protocol）
  • 初期URI（initial URI）
  • メディアタイプ（media types）
  • リンク関係（link relations）

AtomPubを例にとると分かりやすいでしょう。

  • 通信プロトコル＝HTTP
  • 初期URI＝サービス文書のURI
  • メディアタイプ＝「application/atomsvc+xml」「application/atom+xml」など
  • リンク関係＝「rel="edit"」「rel="next"」など

これ以上の知識、たとえば Twitter API のようなURIセットなどは、RESTの定義上、不要というわけです。

Fielding氏の主張

これが腑に落ちれば、Fielding氏の記事に書かれている：

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.

REST APIs must be hypertext-driven

REST APIを記述するための努力は、リソースを表現したりアプリケーションの状態を駆動するために利用されるメディアタイプを定義することや、拡張された関連名や既存の標準メディアタイプに対するハイパーテキスト可能なマークアップを定義することに、ほとんどすべてを費やすべきだ。

InfoQ: 何がRESTを良くするか？

という主張がすんなり理解できます。メディアタイプとリンク関係こそが、RESTful API の核心だからです。

Webアプリへの適用例

Fielding氏の主張を是としてWebアプリに適用する例が、Yahoo! Inc のエンジニア・ Subbu Allamaraju によって書かれています。

API仕様書の例やコーディングの流れが示されていて、有用な記事だと思います。Allamaraju 氏は『RESTful Web Services Cookbook』という本を執筆中（共著）とのことで、こちらも期待できそうです。

メディアタイプの記述例としては Sun Cloud API の定義もあります。

RESTful API では後方互換性を気にする必要がない

さて、上記のように厳格な RESTful API を実装できるのであれば、siena さんが示された「APIの後方互換性」問題：

#rws 後方互換性を破壊するようは変更が出て来ることを考えると。API の非互換バージョンごとに URI セットを振り分けられるようになっているのが望ましい。では、URI に互換バージョンを表す識別子を含めるか。それはそれで気持ちよくない。

http://wassr.jp/user/siena/statuses/A1STwc4qWx

は、そもそも気にならないということになります。互換性が気になるのは、クライアントとサーバが密結合しているサインだといえるでしょう。