@FlaBo APIの使い方
APIキーを取得する
api_auth テーブルに情報を追加する必要があります。
- api_key*(32桁16進) … サービスを識別するコードです
- secret_key*(16桁16進) … @FlaBoとサービスの間でのみ共有されるパスワードです
- hidden_key*(16桁16進) … @FlaBo内部のみで使用されるパスワードです
- title … タイトル
- description … 説明
- callback … コールバックURL(認証ハンドラを作成するの章を確認してください)
(*がついている項目は@FlaBo側で自動的に生成すべき項目です)
ログイン用のリンクを作成する
サービスに@FlaBoの認証をさせます。まずサービス側から@FlaBo認証APIへのリンクを行います。
api_key には先ほど取得した API キーを指定します。一方の api_sig は、このリクエストが開発者本人から送られた正しいものであることを確認するためのシグネチャです。このシグネチャは、同時に指定する他の URL パラメータの値、キー一覧にある秘密鍵の値を使って生成します。
シグネチャの生成ロジックは以下のように実装してください。
- api_sig 以外に指定するパラメータを、パラメータ名でアルファベット順にソートする
- ソートされたパラメータを、"パラメータ名" "そのパラメータの値" の順ですべて文字列連結する
- 秘密鍵とこの連結されたパラメータ文字列「秘密鍵 + 連結したパラメータ文字列」の順で更に文字列連結する
- できあがった文字列を MD5 hex に変換する
例えば
- 秘密鍵が e7b59cdcceaa3904
- api_key が a47d51a93bafc7d1160efd712c6931bd
だった場合、e7b59cdcceaa3904api_keya47d51a93bafc7d1160efd712c6931bd と連結(秘密鍵 + 'api_key' + [api_key の値])した文字列の MD5 を取ります。その値が api_sig の値になります。
正しい api_key と api_sig の組み合わせでリンクを行うと、リンク先で認証が正しく動作します。組み合わせあるいは api_sig の値が正しくない場合は、そのURLへのリクエストは不正なリクエストとして扱われ、リンク先ページはエラー画面となります。
なお、ログイン用URLに api_key や api_sig 以外のパラメータを含めた場合、それらパラメータは次のステップで説明するコールバックURLまで引き継いで渡されます。例えば foo=bar&bar=baz というパラメータをログイン用リンクに追加すると、コールバックURLに cert の他に foo=bar と bar=baz がURLパラメータとして渡ります。
追加パラメータを付与する場合は、シグネチャ生成の際、それらパラメータも含めて値を計算してください。このときパラメータの値は URL エスケープする以前の値を使用してください。
認証ハンドラを作成する
前章で用意したリンクを辿ると、そこでは訪問したユーザーに"該当のサービスに@FlaBoのどのような情報をどれくらいの期間読み取る許可を与えるか"を訪ねるページが表示されます。このページは@FlaBo内に存在します。つまりユーザは、そのサービスにより提供されるログイン用のリンクを辿り@FlaBoにアクセスし、そこで認証許可を確認するという流れになります。
ここでユーザーが許可を与えることに承諾すると、そのユーザーはコールバックURL(キーの設定画面であなたが入力したURL)へとリダイレクトされます。このリダイレクト先のURLには、cert というクエリパラメータが付与されています。
つまり、コールバックURLにはあなたのサービスにおいて認証処理を実行するURLを指定しておき、そのURLをトリガにして走る処理でURLパラメータからcertの値を取得するようにし、その cert パラメータを使って以降の処理を実装していくことになります。
APIを呼び出す
cert の値が取得できたら、欲しい情報を開示するAPIのURL、ここではハンドルネームの開示を行うAPI (http://api.atfb.jp/profile.php) に HTTP GET リクエストを投げます。このとき GET リクエストに以下の三つの値をURLパラメータとして指定します。
- api_key
- time
- cert
- api_sig
api_key はステップ2に同じ値です。certはコールバックURLのURLパラメータから取得したもの、timeは現在の時刻をUNIXタイムスタンプの値で、api_sigは前述と同じ手順で作成します。
つまり、秘密鍵 + 'api_key' + [api_keyの値] + 'cert' + [certの値] ですので、先の例でいくとe7b59cdcceaa3904api_keya47d51a93bafc7d1160efd712c6931bdcert70d3ecd794c46174a905e5438863cb3ctime1198569410 となる文字列の MD5 を取ったものが api_sigの値になります。
この URL へ HTTP GET リクエストを送ると、ユーザー情報が Serialize で返却されてきます。例えば以下のようになります。
a:3:{s:6:"expire";s:16:"2007/12/25 17:57";s:9:"has_error";b:0;s:4:"user";a:2:{s:2:"no";i:1;s:6:"handle";s:4:"Imos";}}
もしパラメータにtype=jsonと加えれば(ただしapi_sigはtypeも含めて再計算する必要があります)
{
"expire" : "2007/12/25 16:12",
"has_error" : false,
"user" : {
"no" : 1,
"handle" : "Imos"
}
}
のように表示されます。
他にも type=xml とすれば XML 形式での取得も可能です。
この情報をパースしてアプリケーションにユーザー情報を取り込んでください。取得したユーザー情報とアプリケーションのセッションとの紐づけは、各アプリケーションでセッション管理用 Cookie を発行してそこへ紐づけるなどして実装してください。
なお、 cert パラメータは期限内であれば何度でも使い回すことができますが、同一の api_sig は拒否されます。ですのでもし1秒間の間に何度もアクセスする可能性がある場合はマイクロ秒などを使ってダミーのパラメーターを追加する等して api_sig が変わるようにしてください。
