OTCHY.NET

≫Download

概要

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

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

特徴

• 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" のサポート

TODO

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