API

Chaton system provides a simple API on http to access chat rooms programatically. The API is under active development, and can be changed frequently without notice. Monitor Chaton room to follow the discussion on API.

Chatonはプログラムによってチャットルームにアクセスするhttp上の簡単な APIも提供しています。APIはまだ開発中で、予告なしに頻繁に変わる可能性 があります。興味のある方は Chaton部屋を ウォッチしていてください。APIに関する議論や要望も歓迎です。

This is a provisional API. Substitute $ROOM by the URL of the room; e.g. for the Gauche room, use http://chaton.practical-scheme.net/gauche/

Reference implementation of the client code in Gauche is in the code repository.

暫定APIです。 $ROOMとあるところはチャットルームのURLに置き換えてください。 たとえばGauche部屋なら http://chaton.practical-scheme.net/gauche/ といった具合に。

Gaucheによるクライアント側コードの参照実装がリポジトリにあります。

Common notes

• Currently Chaton API access is open to everyone and requiring no registration. I don't expect there will be too many applications that causes server problem. If you're a developer, please peek at Chaton room time to time, in case if we experience problems caused by applications.

• A client id (cid) is a transient token to identify an instance of running application; you can think it as a kind of session id. You can get a new cid through the login procedure described below.

• Position (pos) is a kind of cursor that indicates a position in a chat log. It is an integer but the value itself is only meaningful for the server internally; the client application have to treat it as an opaque value. (The treatment of 'pos' value is somewhat incomplete now, since currently it is invalidated when the active log is truncated. It will be addressed in future.)

Login

• URL: $ROOM/apilogin
• Method: POST
• Parameters:
  • who : (required) The name and short description of your application. This is for logging purpose.
  • s : (optional) Specifies the format of the result. "1" for S-expression, "0" for JSON. The default is "1".
• Return value: An S-expression that represents an associative list, or a JSON map. Currently it includes the following elements:
  • post-uri : (string) An URL to which you submit the post text request.
  • comet-uri : (string) An URL to which you submit observe request.
  • cid : (integer) Your application's cid. Use this for subsequent access. You have to call observe immediately to keep the cid valid.
  • pos : (integer) A cursor indicates the most recent position in the room's chat log.

Observe

• URL: given in the reply of the login process
• Method: GET
• Parameters:
  • p : (required) The current position (usually the last 'pos' value returned from the server).
  • c : (required) cid
  • s : (required) The result format. "0" for JSON and "1" for a-list in S-expr.
  • (Note: The call may not return an error if you omit these required parameters. It is the mode used for web interface. For API access, you should always provide these parameters.)
• Return value: (either JSON or a-list)
  • pos : (integer) a new position
  • cid : (integer) your cid. (Note: the server may assign new cid. If that happens, you have to use the new cid for the subsequent access.)
  • nc : (integer) the number of clients connecting to the room.
  • ver : (string) a string identifies the server version. This is used for browsers to detect it needs to refetch the Javascript. Applications don't need to care.
  • content : (an array for JSON, a list for S-expr) a piece of chat log, between the 'p' parameter you given and the 'pos' parameter the server returns.
    In S-expr mode, it is a list of the following entries:

    (<nickname> <timestamp> <said-text>)
    

    where <timestamp> is (<seconds> <microseconds>).
    In JSON mode, lists are represented in arrays.

If the 'p' value you give to the server points before the end of the current log, the server immediately replies. Otherwise, the server holds the request until one of the following conditions is met:

• An active log is changed
• The number of clients is changed
• A hard timeout (4-6minutes) reached

In the latter two cases, 'content' field may be empty.

When the application gets a response, it must reconnect to the observer url immediately. The server only waits 10 seconds for reconnection; if you fail to reconnect, the server thinks you've logged out. (This rather short timeout is set so that we can detect whether a user accessing by a browser is gone.)

Post

• URL: given in the reply of the login process
• Method: POST
• Parameters:
  • nick : the nickname of the poster
  • text : the text to say
  • cid : your cid (this is not passed in web forms now, but it will in future).
• Return value: Currently, this returns no meaningful return value; if the POST succeeds probably you're ok. In future we return more meaningful values.