remember the milk API 用 Java クライアントを作る

API キー・共通鍵の入手

まずは Apply for a non-commercial API Key で API キーを発行してもらうための申請を行う。
必要事項を入力して [Apply] を押下すると程なくして API キーと共通鍵がメールで送られてくる。

認証の流れ

User Authentication を参照し、認証の流れを把握する。
今回はデスクトップアプリケーションでの認証を行おうとしているが、
まず frob という文字列を rtm.auth.getFrob で入手する必要があるようだ。
次に API キー, パーミッション, frob, 署名文字列認証用をパラメータに指定して認証 URL を生成し、そこにアクセスして認証を完了する。
認証完了後、rtm.auth.getToken から認証トークンが取得できる。

Java で実装

依存ライブラリは以下の通り。

commons-lang3-3.1.jar
commons-logging-1.1.1.jar
httpclient-4.0.1.jar
httpcore-4.0.1.jar
jsonic-1.2.9.jar

commons-lang3 は Model クラスで ToStringBuilder などのために使用しているが、特に必須というわけではない。

クライアント

とりあえず rtm.auth.getFrob と rtm.auth.getToken を実行するクライアントを作ってみた。
今後、各 API 実行メソッドをここに追加していく感じ。
レスポンスフォーマットに XML か JSON かを選べるようなので、今回は JSON で受け取って特定オブジェクトに変換して返している。

例外

ふたつの役割のために固有の例外を作った。
ひとつは、API の戻り値が「"stat":"fail"」であればエラーを投げるようにするため。
もうひとつは、内部で使っているメソッドが投げる NoSuchAlgorithmException や UnsupportedEncodingException をそのまま外に投げ返すのが個人的にはあんまり見栄えがよくないように思うので、
こいつらをラップするために使用している。

モデル

JSONIC では JSON から Java オブジェクトへのデコードにクラスを指定できるので、レスポンスデータを保持するモデルクラスを作成した。

Util

書名用文字列を生成している。
署名文字列の生成方法は、mixi の OpenSocial REST API 用署名付きリクエストと似ているようで微妙に違うようだ。
うまくやれば共通化できるかもしれないが、今回は別途作成した。
認証用 URL を生成している。
パーミッションの write は read を兼ね、delete は read, write を兼ねるようなので、READ, READ_WRITE, ALL としてみた。

使い方

RtmClient client = new RtmClient(API_KEY, SHARED_SECRET);
GetFrobResult getFrobResult = client.getFrob();
System.out.println(getFrobResult);

String url = AuthUtil.createAuthUrl(API_KEY, SHARED_SECRET, Perms.READ, getFrobResult.getFrob());
System.out.println("以下の URL にアクセスし、認証を完了してください。");
System.out.println(url);
System.in.read(); // URL に遷移して認証を完了するのを待つため

GetTokenResult getTokenResult = client.getToken(getFrobResult.getFrob());
System.out.println(getTokenResult);

frob を入手し、認証用 URL を生成し表示し、トークンの入手を試みている。
認証用 URL にアクセスすると、remember the milk の「Authorize API Access」という画面に遷移するので [OK, I'll allow it] を押下して認証を完了させる。
認証完了後、再開するとトークンの入手に成功する。
認証せずに再開すると「com.zaneli.rtm.RtmException: code=101, msg=Invalid frob - did you authenticate?」が発生する。

認証だけで結構な量になったので今回はここまで。
次回以降、トークンを使用した操作について書こう。

参考 URL : Remember The Milk APIの使い方調査 - mitc - 日記

ザネリは列車を見送った

ブログという名の備忘録