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

<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