9leap APIドキュメント

注意事項

本ドキュメントは、9leapにおけるAPI実装を解説するものです。

本ドキュメントおよびAPIの実装・仕様は予告なく変更されることがあります。大きな変更の際には 9leapの公式Twitterアカウント で告知いたします。

変更履歴

  • 2011/05/26 初版 (9leap TwitterAPIについて)
  • 2011/08/01 第2班 (9leap データベースAPIについて)

9leap TwitterAPI

ゲームのJavaScript内から、プレイヤーのTwitterアカウントに関する情報をJSONP形式で取得するためのAPIです。
(APIの提供は 2011年6月1日から 行われます。) 

http://9leap.net/api/twitter/{path}

現状では以下のエンドポイントへのアクセスが許可されています。

  • http://9leap.net/api/twitter/account/verify_credentials.json
  • http://9leap.net/api/twitter/statuses/home_timeline.json
  • http://9leap.net/api/twitter/statuses/user_timeline.json
  • http://9leap.net/api/twitter/statuses/friends.json
  • http://9leap.net/api/twitter/statuses/follower.json
  • http://9leap.net/api/twitter/statuses/mentions.json

http://9leap.net/api/twitter/{PATH} へのGETリクエストは、 ログイン状況やAPIアクセス回数制限などをチェックしたのち、、プレイヤーのTwitterアクセストークンを用いて http://api.twitter.com/1/{$PATH} (Twitterの公式API) にアクセスし、そのレスポンスボディを(必要に応じて加工したのちに)返します。

アクセスの成功・不成功はHTTPレスポンスのステータスコードに記載されます。

  • 正しくアクセス出来た場合は、「200 OK」のステータスコードを返します。レスポンスボディにはTwitterの公式APIに準ずるJSONP形式の文字列が含まれます。
  • 許可されていない/存在しないエンドポイントへのアクセスは「404 Not Found」を返します。
    {"error","Not Found"}
  • ログインが必要な場合「401 Unauthorized」を返します。 
    {"error","Could not authenticate you."}
    • このステータスコードを受け取った場合の処理には二つの選択肢があります。
      • ログインが必ずしも必要ではない場合、非連携のままプレイを継続してもらう
      • ログインが必ず必要な場合は、以下のコードを実行します。 
        window.location.replace("http://9leap.net/api/login");
  • APIアクセス回数制限を越えている場合は「403 Forbidden」を返します。 
    {"error","API Access"}
    • twitter側だけではなく9leap側でも、APIアクセスの状況に応じて制限を加えることがあります。
    • 目安としては、「1ユーザ・1回のプレイにつき5回まで」としています。
    • 例えば、プレイヤーのすべてのフォロワーを取得する・タイムラインを遡って1000件取得するなどという操作はできません。

ステータスコードに応じた処理の振り分けの形式は特に定めませんが、それぞれの場合に適切な処理を行い、場合によってはプレイヤーへのフィードバックを行うことをおすすめします。

9leap TwitterAPI対応プラグイン

6月1日に、9leapが提供するAPIへのアクセスを容易にするプラグイン「nineleap.enchant.js」をアップデートし、新たにTwitterAPIに対応した v0.2を配布しています。

TwitterAPI対応プラグインは、enchant.js v3.1以降にのみ対応しています。お手持ちのenchant.jsのバージョンをご確認の上、古いバージョンのままの場合はアップグレードしてください。

ダウンロードはこちらから (github.com)

wise9解説記事 「enchant.jsでTwitter連携ゲームを作ろう！ (その1 プラグイン解説編)」

9leap Memory API (通称: データベース機能)

9leapが提供するゲームメモリーのオンラインストレージサービスです。JSONPで取得でき、Ajaxでサーバーにメモリーを保存することが可能です。 (enchant.jsの対応プラグイン「memory.enchant.js」の使用を推奨します)

(これらのAPIの提供は2011年8月1日から行われます。)

http://9leap.net/api/memory/{gameID}/{path}?callback={callback関数}
取得失敗時：callback関数({"code": ステータスコード, "error": エラーメッセージ});

以下のエンドポイントが提供されます。

自分のプレイデータを取得・書き込み

URL: http://9leap.net/api/memory/{gameID}/user_memory.json [GET(データ取得), POST(データ保存)]

ログイン中のユーザ自身が個別で使用できるメモリー、JSON文字列換算で10KBまで使用できます。 

取得時：callback関数({"data": 保存したJSON形式データ, "updated_at": 更新されたUNIX時間, "user": Twitter名, "online": ゲーム中か否か(bool)});
保存時：（成功：Created.(201)、失敗：Internal Server Error.(500)、サイズオーバー：Request Entity Too Large.(413))

他のユーザのプレイデータを取得

URL: http://9leap.net/api/memory/{gameID}/u/{Twitter名}.json [GET(取得)のみ]

ユーザ個別のメモリーにアクセスする。

callback関数({"data": 保存したJSON形式データ, "updated_at": 更新されたUNIX時間, "user": Twitter名,"score": score,"result":result,"first_played":first_played,"last_played":last_played,"played_time":played_time,"profile_image_url":profile_image_url});

最近プレイしたユーザのプレイデータを取得

URL: http://9leap.net/api/memory/{gameID}/recent_memories.json [GET(取得)のみ]

メモリーが存在するすべてのユーザ個別のメモリーを更新順で30件まで取得する。 "max"というクエリで最大取得数を指定できる。（指定しないと30件まで）

URL: http://9leap.net/api/memory/{gameID}/friends_memories.json [GET(取得)のみ]

Twitterでフォローしているユーザのプレイデータを取得

メモリーが存在するすべてのフレンドの個別メモリーを30件まで取得する。"max"というクエリで最大取得数を指定できる。（指定しないと30件まで） 

callback関数([{"data": 保存したJSON形式データ, "updated_at": 更新されたUNIX時間, "user": Twitter名, "score": score,"result":result,"first_played":first_played,"last_played":last_played,"played_time":played_time,"profile_image_url":profile_image_url},…]);

スコアランキング上位のユーザのプレイデータを取得

URL: shttp://9leap.net/api/memory/{gameID}/ranking_memories.json [GET(取得)のみ]

スコアが高い順にユーザ個別メモリーを30件まで取得する。"max"というクエリで最大取得数を指定できる。（指定しないと30件まで）

callback関数([{"data": 保存したJSON形式データ, "updated_at": 更新されたUNIX時間, "user": Twitter名,"score": score,"result":result,"first_played":first_played,"last_played":last_played,"played_time":played_time,"profile_image_url":profile_image_url},…]);

アクセス制限

これらのAPIへのアクセスは、クライアント側のIPアドレスをチェックし、それに基づくAPIアクセス回数制限を設けております。(現時点では、同一ホストからの5同時アクセスまでの制限。)

また、これらのAPIへのアクセスは、9leapにアップロードしたゲームから、そのゲームIDに対応するデータレコードの書き込みへのみ有効です。 但し例外として、ゲーム投稿者はローカル上でも、ブラウザに9leapのセッションを持っていれば、投稿したゲームのデータレコードへアクセスが可能です。 これは、データベース機能を用いたゲームのデバッグや、メモリの初期データ入力等に用いる事が出来ます。

ステータスコード・認証

アクセスの成功・不成功は、以下の様に、HTTPレスポンスのステータスコードに記載されます。

  • 取得成功時は、「200 OK」、
  • 保存成功時は、「201 Created」、
  • なんらかの原因で保存に失敗した場合、「500 Internal Server Error」、
  • サイズオーバーで保存に失敗した場合、「413 Request Entity Too Large」、
  • 対応するゲームメモリーが初期化されておらず見つからない場合、「404 Not Found」、
  • それ以外のAPIアクセス制限や許可されていないアクセスは、「403 Forbidden」

これらのエンドポイントのうち、以下のエンドポイントへのアクセスはログインが必要です。

http://9leap.net/api/memory/{gameID}/user_memory.json
http://9leap.net/api/memory/{gameID}/friends_memories.json

未ログイン時では、「401 Unauthorized」を返します。ゲーム内でログインする為には、以下のコードを実行します。ページが遷移するため、ゲームの状態はすべてリセットされますので、プレイデータの記録が必須となるゲームについては、プレイが始まる前にプレイデータのロードを行ってください。

window.location.replace("http://9leap.net/api/login");

ステータスコードに応じた処理の振り分けの形式は特に定めませんが、それぞれの場合に適切な処理を行い、場合によってはプレイヤーへのフィードバックを行うことをおすすめします。