APIチュートリアル

オリジナル: http://wiki.lingr.com/dev/show/API+Tutorial

翻訳日: 2006/01/26

原文リビジョン: 12

このチュートリアルでは、Lingr APIの使い方について概観を示します。詳細については、APIリファレンスを参照してください。

さて、APIを使ってチャットルームに入室し、"Hello World"と発言し、退室するまでの一連の流れを見てみましょう。

このチュートリアルではHTTPクライアントとしてcurlを使用します。Mac OS Xや様々なLinuxディストリビューションにデフォルトでインストールされていますので、このチュートリアルを試す上では他に何もインストールする必要はありません。

■ APIキーを取得する

Lingr APIを使用するにはAPIキーが必要です。このページから取得してください。

APIが動作しているか見るために、ブラウザに次のアドレスを入力してください。

http://www.lingr.com/api/explore/get_new_rooms?api_key=あなたのAPIキー

XMLでの応答が得られたら、準備完了です。

このチュートリアルでは「0123456789abcdef0123456789abcdef」というAPIキーを使用します。

■ セッションを作る

まず、セッションを作ります。これにはsession.createを呼び出します。

URL        : http://www.lingr.com/api/session/create
Method     : POST
Parameters : api_key=0123456789abcdef0123456789abcdef

ターミナルで次のように入力してください。

curl -d api_key=0123456789abcdef0123456789abcdef http://www.lingr.com/api/session/create

以下のような応答が得られれば成功です。

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <session>9876543210</session>
 <status>ok</status>
</response>

応答には後で使うために必要となるセッションIDが含まれますので、解析して値を取っておいてください。今回はセッションIDとして9876543210が得らたものとします。

10分ごとに少なくとも1回何らかのAPIを実行しなければ、セッションがタイムアウトします。さて、すぐ次に進みましょう。

■ チャットルームに入室する

それでは好きなチャットルームに入室しましょう。ブラウザでルームに入室するときのURLはhttp://www.lingr.com/room/MyFavoriteRoomのようになっていますが、APIを使うためにこれを展開してルームIDを取っておきましょう。

チャットルームに入室するにはroom.enterメソッドを呼び出します。

URL        : http://www.lingr.com/api/room/enter
Method     : POST
Parameters : session=9876543210&id=MyFavoriteRoom&nickname=api-dude

ターミナルから次のように入力してください。

curl -d session=9876543210 -d id=MyFavoriteRoom -d nickname=api-dude http://www.lingr.com/api/room/enter

次のような応答が得られれば成功です。

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <ticket>my-room-ticket</ticket>
 <max_observe_time>80</max_observe_time>
 <occupant_id>my-chatter-id</occupant_id>
 <status>ok</status>
 <occupants>
  ...
 </occupants>
 <room>
  <url>http://www.lingr.com/room/MyFavoriteRoom</url>
  <description>This is really GREAT room!</description>
  <name>My Favorite Room</name>
  <counter>24</counter>
  <max_user_message_id>24</max_user_message_id>
  <id>abcdef12345</id>
  <icon_url>http://images.lingr.com/room/abcdef12345/16x16.gif</icon_url>
  <tags/>
 </room>
</response>

応答には後に必要となるチケットが含まれていますので、解析して取っておいてください。今回はmy-room-ticketという値が得られました。

roonm.getMessageかrooom.observeメソッドは2分ごとに実行しなければチケットがタイムアウトするため、次に急いで進みましょう。

■ 何か発言する

さあ、発言しましょう。

チャットルームで発言するにはroom.sayメソッドを呼び出します。

URL        : http://www.lingr.com/api/room/say
Method     : POST
Parameters : session=9876543210&ticket=my-room-ticket&message=hello+world

ターミナルから次のように入力してください。

curl -d session=9876543210 -d ticket=my-room-ticket -d message=hello+world http://www.lingr.com/api/room/say

次のような応答が返ってくれば成功です。

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <status>ok</status>
 <counter>28</counter>
 <message>
  <text>hello world</text>
  <nickname>api-dude</nickname>
  <client_type>automaton</client_type>
  <timestamp>2007-01-16T16:52:44-08:00</timestamp>
  <icon_url>http://images.lingr.com/user/0/26x26.gif</icon_url>
  <id>28</id>
  <occupant_id>j4ROzTPY9ii</occupant_id>
  <type>user</type>
  <source>api</source>
 </message>
</response>

ブラウザで発言がちゃんと届いたか確認してください。

room.enterメソッドが呼ばれてから2分でチケットがタイムアウトするため、room.sayメソッドは直ちに呼び出してください。

■ 退室する

全て終わりました。さあ、退室しましょう。

チャットルームから退室するにはroom.exitメソッドを呼び出します。

URL        : http://www.lingr.com/api/room/exit
Method     : POST
Parameters : session=9876543210&ticket=my-room-ticket

ターミナルから次のように入力してください。

curl -d session=9876543210 -d ticket=my-room-ticket http://www.lingr.com/api/room/exit

次のような応答が返ってくれば成功です。

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <status>ok</status>
</response>

退室すると、チケットは無効になり再使用は出来ません。ルームを監視していた場合、直ちに応答が返されます。

■ セッションを破棄する

APIの使用が終わったので、セッションを破棄しましょう。

セッションを破棄するにはsession.destroyメソッドを呼び出します。

URL        : http://www.lingr.com/api/session/destroy
Method     : POST
Parameters : session=9876543210

ターミナルから次のように入力してください。

curl -d session=9876543210 http://www.lingr.com/api/session/destroy

次のような応答が返ってくれば成功です。

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <status>ok</status>
</response>

セッションを破棄すると、そのセッションで入室していた全てのルームから自動的に退室し、実行中のルーム監視は直ちに応答を返します。

■ お疲れ様でした!

これで、どのようにLingr APIが動作するかが分かりました。

Lingr APIには他にも、認証やユーザ情報問い合わせなどの機能があります。これらは全て今まで見てきたメソッドと似たような動作をします。APIリファレンスを読んであなたの発想を形にしてください!

そして、あなたがLingr APIを使用してアプリケーションを開発したら、ショーケースのページにて世界に向けて知らせてください。

もしお望みなら、チュートリアル続編をご覧下さい。