TwitAPI.js

Download

概要

Twitter の API を JavaScript から簡単に使うためのライブラリです。 上部の Download リンクより、js ファイルをダウンロードして読み込む事で、専用のプロキシサーバを通じて Twitter API を呼び出す事が出来るようになります。
Twitter API が BASIC 認証をサポートしなくなる事に合わせて、TwitterAPI.js の後継ライブラリとして開発されました。

現在のバージョンは 0.2.1 です。
TwitMgrSplitwit の開発の都合上、必要になった機能については順次追加していったりしていますが、まだ十分に枯れたとは言えません。
動作のおかしい点などあれば、ご連絡頂けると助かります。

特徴

  • OAuth 対応
  • プロキシサーバを経由して Twitter API にアクセス
  • 単一の JS ファイルを読み込むだけでも利用可能
  • コールバック関数として、関数オブジェクトをそのまま渡せる
  • 外部の JS ライブラリに依存していない
  • Twitter API で定義されている全ての API をシームレスに利用可能
  • GET / POST / DELETE 全てのメソッドの API に対応

プロキシサーバについて

JS から OAuth 対応し、かつ全てのメソッドの API に対応するために、TwitAPI.js ではプロキシサーバを利用しています。
デフォルトの設定では、TwitAPI.js 公式の標準プロキシサーバを使用するようになっていますが、これは Google App Engine の無料分を利用して運用されているため、無料分のリソースを使い切ってしまった場合、TwitAPI.js の動作も止まってしまいます。
また、OAuth 認証の画面で表示されるアプリケーション名が「TwitAPI JS」となるため、それが不都合なケースもあるかと思われます。

標準プロキシサーバの利用について特に制限は設けていませんが、上記のような事情があるので、本格的なアプリケーションを構築する場合や、OAuth 認証画面の表記を作成するアプリケーションと揃えて信頼性を向上させたい場合は、別途、プロキシサーバを構築する必要があります。

プロキシサーバについても全てのソースを taj-proxy として公開しているので、必要に応じて独自のプロキシサーバを立ち上げてください。

サンプル

TwitAPI.js を使うと、Twitter API を簡単に呼び出す事が出来ます。

≪Twitter に投稿する≫

function callback() {
	alert('DONE!');
}
var api = new TwitAPI();
api.call('post', 'statuses/update', callback, {'status': 'テスト'});

≪ホーム TL を取得する≫

var api = new TwitAPI();
api.call('get', 'statuses/home_timeline', function(statuses) {
	var html = '';
	for (var i=0; i<statuses.length; i++) {
		var status = statuses[i];
		html += status.user.name + ' : ' + status.text + '<br />';
	}
	document.getElementById('result').innerHTML = html;
});

これらの実際の動作は、TwitAPI.js sample で確認できます。

API ドキュメント

TwitAPI.js ならびにプロキシサーバは、指定された API のパスを透過的に Twitter サーバに投げるため、本家の API ドキュメントの記述をそのまま使用する事が出来ます。
Twitter API については、日本語訳を公開して下さっている方がいるので参考にして下さい。
Twitter API 仕様書 日本語訳

例えば、サンプルで使用した Twitter に投稿する API ですが、Twitter API だと、以下のような URL です。

http://twitter.com/statuses/update?status=[Tweet message]

この URL に対して、POST でアクセスする事になっています。
この場合、TwitAPI.js では下記のように呼び出す事が出来ます。

var api = new TwitAPI();
api.call('post', 'statuses/update', callback, {status: 'Tweet message'});

このように、TwitAPI.js での API 呼び出しは、本家の API の書式にそのまま対応します。

api.call([get|post|delete], [api path], callback, {param1:value1, param2:value2, ...});

なお、callback に何も指定しなければ、実行結果はそのまま捨てられます。

メソッド "jsonp" のサポート

上記 API のメソッドの指定で、"get"、"post"、"delete" を指定した際は、上記の説明通りプロキシサーバを使用しますが、Ver.0.2.0 より新たに "jsonp" が指定可能になりました。

TwitAPI.js はその仕組み上、どのメソッドを使用した時でも JSONP を使う事には変わりないのですが、あえて "jsonp" を指定した場合、プロキシサーバを使わないで Twitter API がサポートしている JSONP の機能を直接利用します。
つまり、GET メソッドでかつ認証不要な API を利用する際は、TwitAPI.js で "jsonp" を指定する事で、プロキシサーバのオーバーヘッドを無くして動作させる事が出来ます。

使い勝手はプロキシサーバを使用した際と同様で、コールバック関数の定義などについては TwitAPI.js 内に隠蔽されたままとなります。

プロキシサーバの指定

自分でプロキシサーバを構築してそれを利用する場合、TwitAPI.js 上で、そのプロキシサーバを指定する必要があります。
プロキシサーバにはサーバのドメインと、ドメインごとに複数設定可能なアプリケーションパスがあるので、それらを指定して TwitAPI オブジェクトを生成します。

var api = new TwitAPI([server url], [app path]);

デフォルトの設定では下記のように指定したのと同じ状態になっています。

var api = new TwitAPI('http://taj-proxy.appspot.com', 'twit-api-js');

動作条件・制限事項・ライセンス

下記のブラウザで動作確認しています。
IE6 / IE7 / Firefox3.6 / Chrome
未確認ですが、IE8 / Safari / Opera あたりでもそのまま動作すると思われます。

情報を送信するメソッドを使用する場合、JavaScript を実行している HTML/JS が UTF-8 で書かれていないと、日本語が文字化けします。

ライセンスは MIT License (日本版 wikipedia の項) で公開します。

更新履歴

Ver.0.1.0 [2010-06-12]
初公開
Ver.0.1.1 [2010-06-17]
TwitterAPI2.js 対応のため、param 値を String でも受け取れるように修正。
Ver.0.1.2 [2010-08-13]
初回認証時、サーバのレスポンスによっては表示がもたつくので、waiting 表示を挿入。
Ver.0.1.3 [2010-08-14]
TwitterAPI2.js の互換性向上のための修正。
Ver.0.2.0 [2011-08-26]
メソッド "jsonp" のサポート
Ver.0.2.1 [2012-06-02]
パラメータの文字列に # が含まれるとそれ以降を無視してしまう不具合の修正。

TODO

  • クッキーによる自動認証を実装?←セキュリティ面から要検討

13 thoughts on “TwitAPI.js

  1. \素晴らしいライブラリの提供ありがとうございます。
    質問なのですが、リスト一覧を取得するときは
    どのようにパラメータ渡せばよいのでしょうか?

    http://api.twitter.com/1/username/lists.xml?cursor=-1
    このようなパラメータを渡すとき

    var api = new TwitAPI();
    api.call( ‘get’, ‘1/username/lists.json?cursor=-1’, callback);

    とやってみたのですが、APIのURLに「?」が含まれるため
    うまくいきませんでした。

  2. Twitter API を呼び出す時に必要なパラメータについては、call メソッドの 4 つめの引数で渡すようになっています。
    また、API のレスポンス形式を指定する xml / json などの指定ですが、TwitAPI.js では、json 固定のため指定する必要がありません。
    従って、ご質問のような場合では、以下のような呼び出し方になります。

    api.call( ‘get’, ‘1/username/lists′, callback, {cursor: -1});

  3. 原因がわかりましたので報告いたします。
    api.call( ‘get’, ‘username/lists′, callback, {cursor: -1});
    で上手くいきました。「1/」が不要だったのです。

  4. 報告ありがとうございました。
    以前の返信では、API のパスまでは気にせずコピーして回答していたので、申し訳なかったです。

  5. Twitter APIの勉強をしているところ、
    こちらのサイトへたどり着きました。

    taj-proxyのソースコードを拝見して参考にしようとしたところ、
    OAuthUtil.javaの
    import com.google.appengine.repackaged.com.google.common.util.Base64;
    にて、
    Use of com.google.appengine.repackaged may result in your app breaking without warning.
    というビルドエラーが出ました。

    なにかご存知ありませんでしょうか?

    こちらの環境
    ■ Windows7 Home Premium 64Bit
    ■ Eclips 3.6.2(Java)
    ■ Java SE Development Kit 6u24
    ■ Eclipsのプラグインは以下のURLでインストール
      Slim3(http://slim3.googlecode.com/svn/updates/)
      GAE(http://dl.google.com/eclipse/plugin/3.6)

  6. JDK のバージョンと GAE のバージョンの組み合わせによっては発生する事があるようです。
    JDK 1.6.0 ではダメで、JDK 1.6.1 では大丈夫という書き込みもありました。
    taj-proxy で使ってしまっていて恐縮なのですが、 repackaged パッケージの中のクラスについては、
    そもそも利用が推奨されていないようです。
    Apache Commons の代替クラスの利用が推奨されています。

    [参考] http://comments.gmane.org/gmane.comp.systems.google-appengine.jre/23246

  7. 返信ありがとうございました。

    Apache Commons の代替クラスを試して見ました。
    「commons-codec-1.6.jar」をDLして、
    http://commons.apache.org/codec/download_codec.cgi

    import org.apache.commons.codec.binary.Base64;
    Base64.encode⇒Base64.encodeBase64String
    としました。

    私が知りたいところの本質ではない為、
    ちゃんと調査していないので、正常動作するか分かりませんがご参考までに。

    どうもありがとうございました。

  8. 恐らくそれで問題ないかと思います。
    報告ありがとうございました。

  9. はじめまして。
    投稿する文字列に’#’が含まれるとこの文字以降が含まれないものが投稿されてしまいます。
    api.call(‘post’, ‘statuses/update’, callback, {‘status’: ‘テスト #testhash’});
    ↑投稿される文字列は「テスト」。
    api.call(‘post’, ‘statuses/update’, callback, {‘status’: ‘テスト %testhash’});
    ↑投稿される文字列は「テスト %testhash」。問題ない。
    何か、特殊な指定の仕方があるのでしょうか?

  10. 返信が遅くなって申し訳ありませんでした。
    不具合の報告ありがとうございます。
    不具合を修正した Ver. 0.2.1 をリリースしたので、こちらをお試し下さい。

  11. Ver. 0.2.1で動作確認しましたが、問題なく投稿できました。
    ありがとうございました。

コメントを残す

メールアドレスが公開されることはありません。