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 にその情報を乗せて返します。フォーマットは JSON と XML の二択のようです。JSON フォーマットを要求する Get API の場合、レスポンスは以下の形。
|javascript| { "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 を対象にしたパーサを書くべきなのかもしれません。
