Lingr API メモ

lingr-api-memo.md

ここでは、Lingr Bot APIについての情報を取り扱わず、Lingr APIについてのみ扱う。

参照

• Lingr API · lingr/lingr Wiki https://github.com/lingr/lingr/wiki/Lingr-API
• APIメモ · tsukkee/lingr-vim Wiki https://github.com/tsukkee/lingr-vim/wiki/API%E3%83%A1%E3%83%A2
• lingr-vim/lingr.py at master · tsukkee/lingr-vim https://github.com/tsukkee/lingr-vim/blob/master/autoload/lingr.py
• pyLingr/pylingr.py at master · yoshiori/pyLingr https://github.com/yoshiori/pyLingr/blob/master/pylingr.py
• API - lingr - Lingr API documentation - Lingr API - Google Project Hosting https://code.google.com/p/lingr/wiki/API
  • とても古く、現在の仕様と合致しない点が多い

エンドポイント

• http://lingr.com/api/

wwwがつかないことに注意。

APIメソッド

• REST（ふわふわ系）
• session/createでセッションを作ってから、それで得たセッションIDと共にその他のメソッドを呼び出す
• HTTPメソッドはGETとPOSTのどちらでも良い（うーん）
  • event/observeだけGETのみ利用可能
• レスポンス
  • JSON形式
  • HTTPステータスコードはエラーがあっても200(OK)が返って来る（うーん）
    • 代わりに、値"status"で結果が示される
      • "ok" と、 "error" のどちらかの値を取る。
  • Content-Typeはapplication/javascript; charset=utf-8（JSONなのに…）

※レスポンスの例を載せていますが、見やすさのために整形してあります。実際は一行です。

• Session
  • session/create
  • session/verify
  • session/destroy
• User
  • user/get_rooms
• Room
  • room/show
  • room/get_archives
  • room/subscribe
  • room/unsubscribe
  • room/say
• Favorite
  • favorite/add
  • favorite/remove
• Event
  • event/observe

Session

session/create

セッションを作る。

引数

• user
  • ユーザーID
• password
  • パスワード。平文なのが泣けます。
    • （そもそも、OAuthみたいな仕組みがないから、ユーザーIDとパスワードがアプリにだだ漏れ🍣）
• app_key
  • 必須ではない。でもApp Keyがあればこのセッションのレート制限が緩くなったりする。

レスポンス例

{
    "nickname": "kumar8600", 
    "public_id": "SaOysG", 
    "session": "ExHqgY", 
    "status": "ok", 
    "user": {
        "name": "kumar8600", 
        "username": "kumar8600"
    }
}

認証失敗時のレスポンス例

{
    "code": "invalid_user_credentials", 
    "detail": "invalid user and/or password", 
    "status": "error"
}

session/verify

セッションを使いまわす（セッションが未だ有効か確認する）。

引数

• session
  • session/create で得たセッションID

レスポンス例

{
    "nickname": "kumar8600", 
    "public_id": "Y1CP5l", 
    "session": "vrLbRW", 
    "status": "ok", 
    "user": {
        "name": "kumar8600", 
        "username": "kumar8600"
    }
}

無効なセッションIDを渡したときのレスポンス例

{
    "code": "invalid_session", 
    "detail": "invalid session", 
    "status": "error"
}

session/destroy

セッションを破棄する。

引数

• session
  • セッションID

レスポンス例

{
    "status": "ok"
}

無効なセッションIDを渡したときのレスポンス例

{
    "code": "invalid_session", 
    "detail": "invalid session", 
    "status": "error"
}

User

user/get_rooms

ユーザーが参加している部屋一覧を得る。

引数

• session
  • セッションID

レスポンス例

{
    "rooms": [
        "momonga", 
        "emacs", 
        "chin_chin_land", 
        "cpp", 
        "cppjp", 
        "qtusers", 
        "yuroyoro_test"
    ], 
    "status": "ok"
}

Room

room/*でなく、rooms/*に変更されたとのコメントあり

room/show

部屋のメンバーと、直近の発言30件を得る。

引数

• session
  • セッションID
• room
  • 部屋ID

レスポンス例

{
    "rooms": [
        {
            "name": "おちんちんランド", 
            "blurb": "ぼくたちの城", 
            "faved_message_ids": [], 
            "id": "chin_chin_land", 
            "is_public": true, 
            "roster": {
                "bots": [
                    {
                        "icon_url": "http://www.gravatar.com/avatar/d41d8cd98f00b204e9800998ecf8427e.jpg", 
                        "id": "imagebot", 
                        "name": "imagebot", 
                        "status": "production"
                    }, 
                    {
                        "icon_url": "http://www.gravatar.com/avatar/d41d8cd98f00b204e9800998ecf8427e.jpg", 
                        "id": "wandbox", 
                        "name": "wandbox", 
                        "status": "offline"
                    }
                ], 
                "members": [
                    {
                        "icon_url": "http://pbs.twimg.com/profile_images/427808239300792320/K4Oa0BEO_normal.png", 
                        "is_online": true, 
                        "is_owner": true, 
                        "name": "kumar8600", 
                        "pokeable": false, 
                        "timestamp": "2014-09-26T00:55:34Z", 
                        "username": "kumar8600"
                    }
                ]
            }, 
            "messages": [
                {
                    "icon_url": "http://pbs.twimg.com/profile_images/450980994984587266/YkS4ap_i_normal.jpeg", 
                    "id": "18810887", 
                    "local_id": null, 
                    "nickname": "ejo090", 
                    "public_session_id": "rIhQez", 
                    "room": "chin_chin_land", 
                    "speaker_id": "ejo090", 
                    "text": "えっ？", 
                    "timestamp": "2014-04-15T16:17:10Z", 
                    "type": "user"
                }, 
                // 省略。こんなのが30件続く
            ]
        }
    ], 
    "status": "ok"
}

room/get_archives

部屋の過去ログを得る。

引数

• session
  • セッションID
• room
  • 部屋ID
• before
  • 最後に得たメッセージのID。（これより過去のメッセージを得る）
• limit
  • 最大何件まで得るか。

レスポンス例

{
    "messages": [
        {
            "icon_url": "http://www.gravatar.com/avatar/82d662897c37d33314a4e6dd5afe2c51.jpg", 
            "id": "18810380", 
            "local_id": null, 
            "nickname": "s_of_p", 
            "public_session_id": "M5vI43", 
            "room": "chin_chin_land", 
            "speaker_id": "s_of_p", 
            "text": "ログ読み ed", 
            "timestamp": "2014-04-15T15:40:05Z", 
            "type": "user"
        }, 
        {
            "icon_url": "http://www.gravatar.com/avatar/82d662897c37d33314a4e6dd5afe2c51.jpg", 
            "id": "18810588", 
            "local_id": null, 
            "nickname": "s_of_p", 
            "public_session_id": "dk6Acy", 
            "room": "chin_chin_land", 
            "speaker_id": "s_of_p", 
            "text": "おちんちんの話しかしてないし、非常に良さがあった。", 
            "timestamp": "2014-04-15T15:51:55Z", 
            "type": "user"
        }
    ], 
    "status": "ok"
}

room/subscribe

部屋を購読する（通知を有効にする）。

引数

• session
  • セッションID
• room
  • 部屋ID。コンマ区切りで複数指定可能。
• reset
  • bool型。恐らくtrueなら、今回指定していない部屋を全て未購読とし、falseなら、そのままにするのだろう。

レスポンス例

{
    "counter": 26018232, 
    "status": "ok"
}

room/unsubscribe

部屋の購読をやめる（通知を無効にする）。

引数

• session
  • セッションID
• room
  • 部屋ID。多分これもコンマ区切りで複数指定可能。

レスポンス例

{
    "counter": 0, 
    "status": "ok"
}

room/say

部屋に発言する。

引数

• session
  • セッションID
• room
  • 部屋ID
• nickname
  • ニックネーム。session/create、session/verifyで得られる。
• text
  • 本文

レスポンス例

{
    "message": {
        "icon_url": "http://pbs.twimg.com/profile_images/427808239300792320/K4Oa0BEO_normal.png", 
        "id": "20272306", 
        "local_id": null, 
        "nickname": "kumar8600", 
        "public_session_id": "VhcIbr", 
        "room": "chin_chin_land", 
        "speaker_id": "kumar8600", 
        "text": "Chimpo", 
        "timestamp": "2014-09-26T03:03:08Z", 
        "type": "user"
    }, 
    "status": "ok"
}

Favorite

favorite/add

メッセージをふぁぼる。

引数

• session
  • セッションID
• message
  • メッセージID

レスポンス例

{
    "message": {
        "icon_url": "http://pbs.twimg.com/profile_images/427808239300792320/K4Oa0BEO_normal.png", 
        "id": "20272306", 
        "local_id": null, 
        "nickname": "kumar8600", 
        "public_session_id": "VhcIbr", 
        "room": "chin_chin_land", 
        "speaker_id": "kumar8600", 
        "text": "Chimpo", 
        "timestamp": "2014-09-26T03:03:08Z", 
        "type": "user"
    }, 
    "status": "ok"
}

favorite/remove

メッセージをあんふぁぼする。

引数

• session
  • セッションID
• message
  • メッセージID

レスポンス例

{
    "message": {
        "icon_url": "http://pbs.twimg.com/profile_images/427808239300792320/K4Oa0BEO_normal.png", 
        "id": "20272306", 
        "local_id": null, 
        "nickname": "kumar8600", 
        "public_session_id": "VhcIbr", 
        "room": "chin_chin_land", 
        "speaker_id": "kumar8600", 
        "text": "Chimpo", 
        "timestamp": "2014-09-26T03:03:08Z", 
        "type": "user"
    }, 
    "status": "ok"
}

Event

event/observe

Cometによるイベント監視。購読している部屋でイベントが起こったらレスポンスを返す（逆に言うと、それまで返さない）。

• ポート8080を使用
• HTTPメソッドはGETのみ
• 購読はroom/subscribeで行う

引数

• session
  • セッションID
• counter
  • カウンター。このメソッドと、room/subscribeのレスポンスにcounterが含まれるので、最も最近に得た値を渡すこと。

レスポンス例

{
    "counter": 26032825, 
    "events": [
        {
            "event_id": 26032825, 
            "presence": {
                "icon_url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xpf1/v/t1.0-1/c15.0.50.50/p50x50/954801_10150002137498316_604636659114323291_n.jpg?oh=ce9f4da4dbdc0609bf25bf500b1683c8&oe=54BE4FF7&__gda__=1422939042_2465dae62d8ff9224cd283d38ca7e7cb", 
                "nickname": "kumar17200", 
                "public_session_id": "DmJRkc", 
                "room": "chin_chin_land", 
                "status": "online", 
                "text": "kumar17200 is now online", 
                "timestamp": "2014-09-27T00:16:20+00:00", 
                "username": "kumar17200"
            }
        }
    ], 
    "status": "ok"
}

{
    "counter": 26032943, 
    "events": [
        {
            "event_id": 26032943, 
            "message": {
                "icon_url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xpf1/v/t1.0-1/c15.0.50.50/p50x50/954801_10150002137498316_604636659114323291_n.jpg?oh=ce9f4da4dbdc0609bf25bf500b1683c8&oe=54BE4FF7&__gda__=1422939042_2465dae62d8ff9224cd283d38ca7e7cb", 
                "id": "20279450", 
                "local_id": "pending-DmJRkc-1", 
                "nickname": "kumar17200", 
                "public_session_id": "DmJRkc", 
                "room": "chin_chin_land", 
                "speaker_id": "kumar17200", 
                "text": "tinko", 
                "timestamp": "2014-09-27T00:29:26Z", 
                "type": "user"
            }
        }
    ], 
    "status": "ok"
}

失敗時

https://gist.github.com/kumar8600/df2688b7bbc4f8fd28ba#gistcomment-1445026

room/subscribe, room/show などのパラメータ room が rooms に変わったようです

event/observe ですが、メンテナンスで落ちた場合は JSON でレスポンスを返さずかの有名な犬画面の HTML を返してきます。

参考:

@zk-phi @0xBADDCAFE ありがとうございます。その旨書き加えます。