---

API Methods

All API methods are pre-pended by the URL of the site (http://tapingya.appspot.com).  This URL may change in the future.  For example, to get a list of rooms, make an HTTP GET request to the following:

http://tapingya.appspot.com/api/rooms

All methods use basic HTTP GET or POST requests.  Results are always in JSON format or plain text.  XML is not supported currently.

Samples and libraries can be found at TaPingYa API Files and Samples.

JSON Results

Messages
Below is a sample JSON result for message requests.

{"servertime":"2008/10/09 19:31:47 +0000","messages":[{"creator":"testuser","alias":"testuser","source":"","key":"agh0YXBpbmd5YXIOCxIHTWVzc2FnZRjeCQw","time":"2008/10/09 18:13:06 +0000","message":"yeah, it was before the test. oh well","type":0,"id":"1246"}]}

Guests
Below is a sample JSON result for guest requests.

{"guests":[{"guest":"NerdForceMaster"},{"guest":"Scott1055"},{"guest":"bvelasquez"},{"guest":"chris.shumway"},{"guest":"pderksen2"},{"guest":"seankcsci2"}]}

---

Rooms

Returns a list of rooms sorted by name.  Can specify count and page number.

Path :  /api/rooms

Method : GET

Parameters :
count : The number of results you would like.  Default is 25.
page : The page number, from 0-N.  Default is 0.

Result :
Returns a string in JSON format of the rooms.

---

New Rooms

Returns a list of rooms sorted by creation date in descending order.

Path : /api/rooms/new

Method : GET

Parameters :
count : The number of results to return.

---

Updated Rooms

Returns a list of rooms sorted by modified date in descending order.

Path : /api/rooms/updated

Method : GET

Parameters :
count : The number of results to return.

---

Send Ping Request

Posts a ping to the server, indicating that the user that sent the ping is in the room.  This method is useful in indicating presence, without polling for recent messages.

Path : /api/room/ping

Method : POST

Parameters :
count : The number of results to return.

---

Messages for a Room

Retrieves the latest messages for the specified room.

Path : /api/messages

Method : GET

Parameters :
room_id : The ID of the room.
count : The number of results to return.
page : The page number of results.
format : If set to "textile", the results will be formatted according to textile parsing.
password : The room password if one exists.

Result :
Returns a string in JSON format of the messages.

---

Recent Message for a Room

Retrieves only the most recent messages for a room, depending on the number of milliseconds back to look.  This method also signals your presence in a room.  Presence must be reported within 20 second intervals in order to be reported as present in a room.  Activity must be posted in the form of a posted message, link, or task update within 4 hours or the user will be kicked and kick responses returned instead of updates.

Path : /api/messages/recent

Method : GET

Parameters :
room_id : The ID of the room.
timeback : How many milliseconds to look back from UTC now (server time).
count : The number of messages to retrieve.
format : If set to "textile", the results will be formatted according to textile parsing.
password : The room password if one exists.

Result :
Returns a string in JSON format of the messages.

---

Post a Message to a Room

Post a new message to the specified room.

Path : /api/messages/post

Method : POST

Parameters :
room_id : The ID of the room.
message : The message to post.
source : The source of the message (optional).
password : The room password.

Result :
A string of the message key.

---

Create a new Room

Creates a new Room.

Path : /api/room/new

Method : POST

Parameters :
name : The name of the new room.
password : The password to set on the room.
redirect_url : A URL to redirect to after the post.

Result:
Returns the key of the new room.

---

Update an Existing Room

Updates the properties of an existing room.

Path : /api/room/update

Method : POST

Parameters :
room_id : The ID of the room.
name :  The name of the room.
password : The password of the room.
description : The description of the room.
redirect_url : A URL to redirect to after the post.

Result :
The key of the Room.

---

Return Room ID from Key

Returns the Room ID from the Room Key.

Path : /api/room/id

Method : GET

Parameters :
key : The key of the room.

Result :
The ID of the Room.

---

Return Room Key from ID

Returns the Room Key from the Room ID

Path : /api/room/key

Method : GET

Parameters :
room_id : The ID of the room.

Result :
The key of the room.

---

Active Guests in Room

Retrieves the currently active guests.  Guests are active if they are retrieving recent messages or sending ping requests.

Path : /api/room/guests

Method : GET

Parameters :
room_id : The ID of the room.
secondsback : How many seconds back the Guest must have pinged or requested recent messages.
password : The password of the room.

Result :
Returns a string in JSON format of the guests.

---

Set Guest Avatar

Sets the Guests Avatar Image.

Path : /api/guest/image/set

Method : POST

Parameters :
avatar : The image.
redirect_url : A URL to redirect to after the post.

Result :
Returns the Guest Key.

---

Get Guest Avatar

Retrieves the Guests Avatar.

Path : /api/guest/image/get

Method : GET

Parameters :
handle : The handle of the guest.  The handle is the Google Nickname.

Result :
Returns the image.  Content type is image/png.

---

Set Guest Profile

Sets the Guests Profile properties.

Path : /api/guest/profile/set

Method : POST

Parameters :
status : The status message for the guest.
alias : An alias to use instead of the default Google nickname.
redirect_url : A URL to redirect to after the post.

---

Kick Guest

Kicks the guest from the room, which removes them from the room and stops sending updates on their request.  This is used to remove campers or forgotten sessions.  This can only be executed by the room owner.

Path : /api/guest/kick

Method : POST

Parameters :
room_id : The ID of the room to kick them from.
nickname : The nickname of the guest to kick.
duration : How long (in seconds) before they can re-enter.