9leap APIドキュメント

Important Points

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

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

Changelog

  • 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アクセストークンを用いて https://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関数({
  "twitterID": Twitterのuser_id,
  "name": Twitter名,
  "profile_image_url": Twitterのプロフィール画像,
  "data": 保存したJSON形式データ,
  "updated_at": 更新されたUNIX時間,
  "screen_name": 9leap.netでの表示名,
  "score": スコア(点数),
  "result": プレイ結果の文字列,
  "first_played": 最初にプレイされたUNIX時間,
  "last_played": 最後のプレイされたUNIX時間,
  "played_time": プレイした回数 
});
(※ 実データには改行は含まれません)

保存時

(成功:Created.(201)、失敗:Internal Server Error.(500)、サイズオーバー:Request Entity Too Large.(413))

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

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

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

callback関数({
  "twitterID": Twitterのuser_id,
  "name": Twitter名,
  "profile_image_url": Twitterのプロフィール画像,
  "data": 保存したJSON形式データ,
  "updated_at": 更新されたUNIX時間,
  "screen_name": 9leap.netでの表示名,
  "score": スコア(点数),
  "result": プレイ結果の文字列,
  "first_played": 最初にプレイされたUNIX時間,
  "last_played": 最後のプレイされたUNIX時間,
  "played_time": プレイした回数 
});

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

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

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

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

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

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

callback関数([
  {
    "twitterID": Twitterのuser_id,
    "name": Twitter名,
    "profile_image_url": Twitterのプロフィール画像,
    "data": 保存したJSON形式データ,
    "updated_at": 更新されたUNIX時間,
    "screen_name": 9leap.netでの表示名,
    "score": スコア(点数),
    "result": プレイ結果の文字列,
    "first_played": 最初にプレイした日時 "YYYY-MM-DD HH:mm:ss"形式,
    "last_played": 最後にプレイした日時 "YYYY-MM-DD HH:mm:ss"形式,
    "played_time": プレイした回数 
  }
,...]);
(※ 実データには改行は含まれません)

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

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

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

callback関数([
  {
    "twitterID": Twitterのuser_id,
    "name": Twitter名,
    "profile_image_url": Twitterのプロフィール画像,
    "data": 保存したJSON形式データ,
    "updated_at": 更新されたUNIX時間,
    "screen_name": 9leap.netでの表示名,
    "score": スコア(点数),
    "result": プレイ結果の文字列,
    "first_played": 最初にプレイした日時 "YYYY-MM-DD HH:mm:ss"形式,
    "last_played": 最後にプレイした日時 "YYYY-MM-DD HH:mm:ss"形式,
    "played_time": プレイした回数 
  }
,...]);
(※ 実データには改行は含まれません)

アクセス制限

IP addresses of clients that attempt to access these APIs are checked, and the number of times access can be attempted to a given API is limited to a set number of times. (At this time, the same host may attempt access up to 5 times.)

Also, access to these API's, when made from games uploaded on 9leap, can only work when writing to the data record specified by that game's ID. However, as an exception, if the poster of a game is working with a local version, as long as there is a valid session with 9leap in the browser, the data record for the posted version of the game can be accessed. This can be used for debugging a game that uses database functionality, or for entering data into live, initialized memory, etc.

Status code/Authentication

The successful or unsuccessful status of an connection attempt will result in the issuing of the following HTTP response codes.

  • If acquisition succeeded, “200 OK” will be returned.
  • If saving succeeded, “201 Created” will be returned.
  • If saving failed for some reason, “500 Internal Server Error” will be returned.
  • If saving is attempted on a file that is too large, “413 Request Entity Too Large” will be returned.
  • If access is attempted on initialized game memory, “404 Not Found” will be returned.
  • If access is attempted outside of the limits or permissions of the access API, “403 Forbidden” will be returned.

When accessing the following endpoints from a given endpoint, login is required.

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

When a user is not logged in, a "401 Unauthorized" message will be returned. To prompt a user to login inside of the game, use the following code. Since this causes a transition between pages, this will also cause a game to completely reset. If a game requires memory of any kind, please have this code load before your game begins.

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

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