I had someone ask about this so I decided to go ahead and post something. Below is the contents of a Word doc that describes our REST API for working with Team Rooms. It should work both on Team Foundation Service and on a public preview of TFS 2013. Please let me know if you have any feedback on the doc.
This is a very early preview and we’ll launch it officially later this year. It’s also incomplete but it’s a start. Hopefully it will give you what you need to know to do basic Team Room extensions. Ultimately we’ll follow up with samples and more but right now we’re trying to get TFS 2013 finished up.
Brian
ChatRoom Service
General Information
Service Name | ChatRoom service |
Area | Chat |
Version | V1 |
Application URL | N/A |
Account URL | {account}.visualstudio.com/DefaultCollection/_apis/Chat |
Description
The ChatRoom service allows users to interact with their team chat rooms. The service allows developer-centric users to real-time collaborate with their team.
The Team Chat Room must be open for allowing authenticated extensions to communicate. This will allow other services within Microsoft and external 3rd party apps to perform basic operations on the team room such as the following:
· room-level operations such as create(or delete) rooms, get a list of rooms, etc
· user-level operations such as join(or leave) a given user from a team room,
· message-level operations such as post a message, get a list of messages (recent, given day or given time window)
By default chat rooms created by the chat service live at the collection level and have no affiliation with a team in TFS. However, we will be automatically creating a chat room for each TFS team. This room will be stored as a team favorite and show up on the team homepage.
Resources
Resources | Description |
/rooms | Represents chat room resource container |
Represents chat users resource container | |
Represents chat messages resource container |
API Flows
Some of the common flows are as follows:
User joins a given team room to chat
A chat client with a given user's credentials, gets a list of team rooms, joins a given team room, retrieves transcripts, posts a message to the team room, leaves the team room.
Verb | Request & Response | API Details |
GET | /rooms · 200: Wrapped array of team room information | |
POST | /rooms/{roomId}/users · 201: User joins the given chat room | |
GET | /rooms/{roomId}/messages · 200: Wrapped array/ transcript of chat messages from the given chat room | |
POST | /rooms/{roomId}/messages · 201: Message posted to the given chat room | |
DELETE | /rooms/{roomId}/users/me · 200: User leaves the given chat room |
NOTE: Streaming APIs will come online at a later date
User status
A chat client with a given user's credentials, would display the list of users currently in the team room. For other regular chat operations, the above API flow works.
Verb | Request & Response | API Details |
GET | /rooms/{roomId}/users · 200: Wrapped array of users currently online in the given chat room |
API Details
This section has the details for each web API. Each individual API goes through a status of review, then once approved it will get a status of the initial production release of v1.preview. This will be covered in more detail in the versioning doc.
Get Rooms
Retrieve chat rooms in a given account, the account information is retrieved from the URL.
Status | V1 |
GET | /chat/Rooms |
Params | Check OData filters below |
Response Body | { { { |
Return Codes | 200:OK– success |
Create Chat Room
Create a new chat room in a given account.
Status | V1 |
POST | /Chat/Rooms |
Params | { "Name":"NewRoom", "Description":"Description1" } |
Response Body | { "id":2,"name":"NewRoom", "description":"Description1", "lastActivity":"2013-04-11T00:32, "creatorUserTfId":"edfab9de-17c2-49ef-99cb-abfc159a1224", "createdDate":"2013-04-11T00:32:29.673Z" } |
Return Codes | 201:Created– success |
Get Room Info
Gets individual chat room information such as name, description.
Status | V1 |
GET | /Chat/Rooms/{RoomId} |
Params | |
Response Body | { "id": 2, "name": "Second Room", "description": "", "lastActivity": "2013-03-22T19:53:33.683Z", "isClosed": false, "creatorUserTfId":"4ea29d8a-00d9-4e76-b798-f6be3b0967c0", "createdDate": "2013-03-22T19:53:33.683Z" } |
Return Codes | 200:OK– success |
Update Room Info
Updates a given chat room's information such as name, description.
Status | V1 |
PATCH | /Chat/Rooms/{RoomId} |
Params | { "Name":"New Room Name", "Description":"Updated Description" } |
Response Body | |
Return Codes | 200:OK– success |
Delete a Room
Deletes a given chat room.
Status | NOT IMPLEMENTED YET |
DELETE | /Chat/Rooms/{RoomId} |
Params | |
Response Body | |
Return Codes | 200:OK– success |
Get users in a room
Gets a list of currently online users in a given team room
Status | V1 |
GET | /Chat/Rooms/{RoomId}/Users |
Params | Odata filters applicable here |
Response Body | { |
Return Codes | 200:OK– success |
Get user status info
Gets status of a given user in the context of a given chat room. The ‘me’ resource is a special resource to store the currently logged in user.
Status | V1 |
GET | /Chat/Rooms/{RoomId}/Users/UserId or /Chat/Rooms/{RoomId}/Users/me |
Params | |
Response Body | { |
Return Codes | 200:OK– success |
Join room
Joins the currently authenticated user to a given team room
Status | V1 |
PUT | /Chat/Rooms/{RoomId}/Users/UserId or /Chat/Rooms/{RoomId}/Users/me |
Params | { |
Response Body | |
Return Codes | 200:OK– success |
Leave room
Leaves the currently authenticated user from a given team room
Status | Review (Review, v1.preview, v1, etc…) |
DELETE | /Chat/Rooms/{RoomId}/Users/UserId or /Chat/Rooms/{RoomId}/Users/me |
Params | |
Response Body | |
Return Codes | 200:OK– success |
Post message
Posts a message to a given team room
Status | Review (Review, v1.preview, v1, etc…) |
POST | /Chat/Rooms/{RoomId}/Messages |
Params | { "content": “Message content” } |
Response Body | Location header contains message Id Rooms/{RoomId}/Messages/{MessageId} |
Return Codes | 201:Created – success |
Get chat transcript
Gets a given room's chat messages transcript.
Status | Review (Review, v1.preview, v1, etc…) |
GET | /Chat/Rooms/{RoomId}/Messages |
Params | Odata params applicable here |
Response Body | { |
Return Codes | 200:OK– success |
Get a given message
Gets a given message in a given chat room
Status | V1 |
GET | /Chat/Rooms/{RoomId}/Messages/{MessageId} |
Params | |
Response Body | { |
Return Codes | 200:OK– success |
Update a given message
Updates a given message in a given chat room
Status | NOT IMPLEMENTED YET |
PATCH | /Chat/Rooms/{RoomId}/Messages/{MessageId} |
Params | |
Response Body | { "message": “Message content” } |
Return Codes | 200:OK– success |
Delete a given message
Deletes a given message in a given chat room
Status | NOT IMPLEMENTED YET |
DELETE | /Chat/Rooms/{RoomId}/Messages/{MessageId} |
Params | |
Response Body | |
Return Codes | 200:OK– success |