RESTful Web APIs 読書会( 第二回 )に参加してきた

RESTful-Web-APIs

RESTful Web APIs 読書会 #2 に参加してきた。

RESTful Web API？

要約すると以下のような感じ。

・Webサービスだとハイパーリンクとかをたどって ユーザは目的達成できるけど、APIの場合って  多くの場合ドキュメントがWeb上に別個に公開されていて、URLだけ見てもわからない上に、ドキュメントを見ても個々の機能がどのように関連しているかがわかりにくいよね

・そもそも そういうWeb APIのあり方って 自己記述性の点でどうなの？(=RESTfulじゃないよね)

・自己記述的なものが含まれていて、最初のURLさえあれば使い方がわかるようなAPIが理想的だよね

そこで RESTful Web APIの著者は Collection+JSON というフォーマットを推奨している。

Collection+JSONとは？

JSONが汎用的でプレーンテキストを扱うものだとしたら、Collection+JSON とは JSONよりも限定的で 「Web上のリソースの検索可能なリストを公開するための規格」である。

HTTPヘッダでは Content-Type: application/vnd.collection+json という形で渡される。

RESTful Web APIs 著者がアクセスしたサイトのうち http://youtypeitwepostit.herokuapp.com/app/ にアクセスすると以下のようなJSONデータがGETできる(なお、このURLに関してはレスポンスのContent-Typeに上記の形式が返され、これは主要ブラウザが現在認識しないため ダウンロードが行われる)。


{
  "collection" :
  {
    "version" : "1.0",
    "href" : "http://youtypeitwepostit.herokuapp.com/api/",

    "items" : [
      {
        "href": "http://youtypeitwepostit.herokuapp.com/api/613856331910938",
        "data": [
          {
            "name": "text",
            "value": "Squid!"
          },
          {
            "name": "date_posted",
            "value": "2013-03-28T21:51:08.406Z"
          }
        ]
      }
    ],

    "template" : {
      "data" : [
        {"prompt" : "Text of message", "name" : "text", "value" : ""}
      ]
    }
  }
}

まず collection という属性があり、items には リソース一覧が返される。リソースにはhref、name、valueがついているが、これがリソースの自己明示性を保つのに一役買っている。

さらに、API経由で データのPOSTを行いたい場合どうすれば良いのかもこのオブジェクトの中に書かれていて、これがWebサイトで言うハイパーメディアの役割を果たしている(「template」の中に書かれたdata属性が持つオブジェクトの形式に沿ってPOSTを行う)。

この構造によって 従来のJSONが表現しづらかった「リンク」を表現できる。なるほど確かにRESTful。

“constraints can be liberating. ( 「制約」により自由になる )”

という言葉は特に印象に残っている。

次回の読書会は 11/14(木) 19:30 から。楽しみ。

(ところで、結局「Squid」って何だったんだろう)

Written by Nisei Kimura ( 木村 仁星 )

- Sponsored Links -

<<

Top

>>