REST API for Team Rooms

Brian Harry

July 22nd, 20130 0

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 3^rd 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
<RoomUri>/users	Represents chat users resource container
<RoomUri>/messages	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	Get a list of rooms
POST	/rooms/{roomId}/users · 201: User joins the given chat room	User joins a given room
GET	/rooms/{roomId}/messages · 200: Wrapped array/ transcript of chat messages from the given chat room	Gets room transcript
POST	/rooms/{roomId}/messages · 201: Message posted to the given chat room	Send a message
DELETE	/rooms/{roomId}/users/me · 200: User leaves the given chat room	Leave 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

Get list of users statuses

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	{ “count”: 2, “value”: [ { “id”: 1, “name”: “First Room”, “description”: “RoomDescription”, “lastActivity”: “2013-04-11T00:32:29.673Z”, “isClosed”: false, “creatorUserTfId”: “edfab9de-17c2-49ef-99cb-abfc159a1224”, “createdDate”: “2013-0411T00:32:29.673Z” } { “id”: 2, “name”: “Updated Room Name”, “description”: “Updated Description”, “lastActivity”: “2013-04-11T00:32:29.673Z”, “isClosed”: false, “creatorUserTfId”: “edfab9de-17c2-49ef-99cb-abfc159a1224”, “createdDate”: “2013-0411T00:32:29.673Z” } ] }
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 404: Not Found– Room not found

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 404: Not Found– Room not found

Delete a Room Deletes a given chat room.

Status	NOT IMPLEMENTED YET
DELETE	/Chat/Rooms/{RoomId}
Params
Response Body
Return Codes	200: OK– success 404: Not Found – Room not found

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	{ “count”: 1, “value”: [ { “roomId”: 1, “userId”: “b918ff7a-52f7-4bdf-8186-2d5cdbf707d7”, “lastActivity”: “2013-04-11T00:43:35.903Z”, “joinedDate”: “2013-04-11T00:43:35.903Z” } ] }
Return Codes	200: OK– success 404: Not Found – Room not found

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	{ “roomId”: 1, “userId”: “b918ff7a-52f7-4bdf-8186-2d5cdbf707d7”, “lastActivity”: “2013-04-11T00:48:02.69Z”, “joinedDate”: “2013-04-11T00:48:02.69Z” }
Return Codes	200: OK– success 404: Not Found – Room not found/ user not present in room

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	{ “UserId”: “b918ff7a-52f7-4bdf-8186-2d5cdbf707d7” }
Response Body
Return Codes	200: OK– success 404: Not Found – Room not found

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 404: Not Found – Room not found/ user not present in room

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 404: Not Found – Room not found

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	{ “count”: 2, “value”: [ { “id”: 97, “content”: “First message in the room”, “messageType”: “normal”, “postedTime”: “2013-04-11T01:01:09.097Z”, “postedRoomId”: 1, “postedByUserTfid”: “b918ff7a-52f7-4bdf-8186-2d5cdbf707d7” }, { “id”: 98, “content”: “Hello”, “messageType”: “normal”, “postedTime”: “2013-04-11T01:01:11.69Z”, “postedRoomId”: 1, “postedByUserTfid”: “b918ff7a-52f7-4bdf-8186-2d5cdbf707d7” } ] }
Return Codes	200: OK– success 404: Not Found – Room not found

Get a given message Gets a given message in a given chat room

Status	V1
GET	/Chat/Rooms/{RoomId}/Messages/{MessageId}
Params
Response Body	{ “id”: 97, “content”: “First message in the room”, “messageType”: “normal”, “postedTime”: “2013-04-11T01:01:09.097Z”, “postedRoomId”: 1, “postedByUserTfid”: “b918ff7a-52f7-4bdf-8186-2d5cdbf707d7” }
Return Codes	200: OK– success 404: Not Found – Room/Message not found

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 404: Not Found – Room/Message not found

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 404: Not Found – Room/Message not found

REST API for Team Rooms

Brian Harry Corporate Vice President, Cloud Developer Services

0 comments

REST API for Team Rooms

Brian Harry Corporate Vice President, Cloud Developer Services

Read next

0 comments