理系学生日記

おまえはいつまで学生気分なのか

忍者TOOLS

Read It Later の API

Read It Later に対する Perl からのインタフェースを WebService::Simple を使って作る過程で学んだことをまとめます。 とはいえ、非常にシンプルなので、公式のリファレンスを読んだ方が分かりやすいとは思います。

API

Read It Later の API は以下のような非常にシンプルな体系になっています。

  • リスト管理
    • Add: 新規にページ(1ページに限定)を追加する
    • Send: 一気に既読にしたり、一気にページを追加するなど、「一度に」何かをしたいときはこの API を呼ぶ
    • Get: ユーザが Read It Later に登録しているリストを取得する
    • Stats: ユーザがどれだけ Read It Later にページを登録しているか等の情報を取得する
  • アカウント管理
    • Authenticate: ユーザ認証を行う
    • Signup: 新規ユーザを登録する
  • ページコンテンツの取得
    • Text: ページのコンテンツを実際に取得する(試してない)
  • API
    • API: Read It Later の API の呼び出し頻度には制限があり、その制限に関する情報を取得する

Read It Later の API は、twitter などと同様に、1 apikey からのリクエスト上限が設定されています。
一定時間(30 分とか 1 時間レベルだと思います)経つとそれまでのリクエスト回数がリセットされ、また使えるようになります。

リクエスト

リクエスト自体は、POST、GET、どちらにも対応しています。
体系も、各 API 用に割り当てられている URL に対してリクエストを送る、パラメータは QUERY_STRING の形という、一般的なものです。

レスポンス

Read It Later は、そのレスポンスの大部分を、HTTP レスポンスヘッダに乗せて返します。以下は API のドキュメントに乗ってる例。

Status: 200 OK
X-Limit-User-Limit: 100
X-Limit-User-Remaining: 43
X-Limit-User-Reset: 25
X-Limit-Key-Limit: 5000
X-Limit-Key-Remaining: 3520
X-Limit-Key-Reset: 25

Get API や Stats API などの「情報取得」系の API に関しては、HTTP BODY にその情報を乗せて返します。フォーマットは JSONXML の二択のようです。JSON フォーマットを要求する Get API の場合、レスポンスは以下の形。

{
   "status":"1",			// 1=normal, 2=no changes since your provided 'since'
   "since":"1245626956",		// timestamp of this response
   "list":{
      "93817":{
         "item_id":"93817"		    // unique id identifying the url
         "url":"http://url.com",
         "title":"Page Title",
         "time_updated":"1245626956",       // time the item was last added/changed
         "time_added":"1245626956",	    // time item was added to list
         "tags":"comma,seperated,list",
         "state":"0",                       // 0=unread, 1=read
      },
      "935812":{
         "item_id":"935812"		    // unique id identifying the url
         "url":"http://google.com",
         "title":"Google",
         "time_updated":"1245626956",       // time the item was last added/changed
         "time_added":"1245626956",	    // time item was added to list
         "tags":"comma,seperated,list",
         "state":"1",                       // 0=unread, 1=read
      }
   }
}	

かなりの API がヘッダ行のみで情報をやりとりするにも関わらず、一部 API は HTTP BODY にも情報を乗せるので、WebService::Simple を Read It Later に使う場合は、ヘッダと BODY を対象にしたパーサを書くべきなのかもしれません。