[Communication - Rooms] REST API Review

[Hiro7]

Key contact for the review:
[e-mail]

Whether this is a new or existing API:
New API

PR
#19269

Hero scenarios:

Following champion scenarios illustrate how Contoso can use Azure Communication Services Rooms APIs to create a server-managed communication space for fixed set of participants, controlling both who and when can communicate.

Contoso College

Contoso College is a fictional educational institution that provides both on-campus and online programs. Contoso College administrator would like to create a virtual space/room for each offered course where course owner can hold virtual meetings and exchange messages with students. Only registered students should have access to associated room.

Prerequisites

Contoso College needs to have a provisioned an Azure Communication Service resource.

Scenarios

Simple Room Lifecycle

When defining new schedule for semester, Contoso College administrator wishes to pre-create a room for every course, set fixed start and end time for each room and register participants.
Rooms are server-side managed resources, only administrator has direct access to create, view, update and delete rooms.

RoomClient initialization

Administrator first needs to obtain the connection string from the Keys section of their Communication Service instance.

var connectionString = "<connection_string>"; // Find your Communication Services resource in the Azure portal
RoomsClient client = new RoomsClient(connectionString);

Create Room

The administrator creates an empty room with default setup.

CreateRoomRequest createRoomRequest = new CreateRoomRequest();
Response<RoomResult> createRoomResponse = await roomsClient.CreateRoomAsync(createRoomRequest);
RoomResult createRoomResult = createRoomResponse.Value;
string roomId = createRoomResult.Id;

Contoso administrator associates it with a college course and stores the ID into their local database.

View details of existing room

If administrator wants to view room lifetime and participants, they can use a Get request.

Response<RoomResult> getRoomResponse = await roomsClient.GetRoomAsync(
    createdRoomId: "existing room Id from previous step")
RoomResult getRoomResult = getRoomResponse.Value;

Update room lifetime

Using update API, administrator can update start and end time of the room, or modify it's participants.

UpdateRoomRequest updateRoomRequest = new UpdateRoomRequest()
{
    ValidFrom = new DateTimeOffset(2021, 8, 1, 8, 6, 32,
                                 new TimeSpan(1, 0, 0)),
    ValidUntil = new DateTimeOffset(2021, 8, 2, 8, 6, 32,
                                 new TimeSpan(1, 0, 0))
    } 
 };
Response<RoomResult> updateRoomResponse = await roomsClient.UpdateRoomAsync(createdRoomId, updateRoomRequest);
RoomResult updateRoomResult = updateRoomResponse.Value;

Add new participants to room

As new students have registered to course, administrator now wishes to add them to room as eligible participants.

UpdateRoomRequest updateRoomRequest = new UpdateRoomRequest()
{
    Participants = {
        { "8:acs:db75ed0c-e801-41a3-99a4-66a0a119a06c_a6eb98f7-83f6-42a2-b507-0711e2f0c2cf", new {} }
    } 
 };
Response<RoomResult> updateRoomResponse = await roomsClient.UpdateRoomAsync(createdRoomId, updateRoomRequest);
RoomResult updateRoomResult = updateRoomResponse.Value;

Remove participants

When needed administrator can also remove individual participants, thus revoking their access in room.

UpdateRoomRequest updateRoomRequest = new UpdateRoomRequest()
{
    Participants = {
        { "8:acs:db75ed0c-e801-41a3-99a4-66a0a119a06c_a6eb98f7-83f6-42a2-b507-0711e2f0c2cf", null }
    } 
 };
Response<RoomResult> updateRoomResponse = await roomsClient.UpdateRoomAsync(createdRoomId, updateRoomRequest);
RoomResult updateRoomResult = updateRoomResponse.Value;

Delete Room

To clean up the resources, administrator can explicitly delete the room.
This step is optional though since all rooms honor their end-time and will be automatically deleted after some buffer time.

Response deleteRoomResponse = await roomsClient.DeleteRoomAsync(
    createdRoomId: "existing room Id which is created already")

Course lecturer starting a video call in the room

This is not a Contoso administrator scenario, so it does not happen via Rooms Management API, but we have included brief version of it here for completeness.

Starting a call takes place on the end-user device, such as Contoso College webpage. The lecturer first logs into Contoso College system and obtains an Azure Communication Services User Access Token.
Using the token, Contoso client application then initializes the ACS Calling SDK and starts new call, by providing the roomID to calling SDK.

[Jeffrey Richter]

I put my comments here: #19269 (review)

[Weidong Xu]

The link to Hero scenarios is 404 for me.

[Hiro7]

@weidongxu-microsoft Scenarios updated ;)

[Mark Weitzel]

API Stewardship Board Review 16-Jun-22

control plane -- this may be confusing for customers because it might be misconstrued as the ARM control-plane. If there is another reasonable choice, it would be good to consider using this.

JSON + Merge-Patch -- See issu 3520. Adapting their API to be more consistent with other ACS services, e.g. ACS Chat

ETags -- Based on expected usage, it's not anticipated that these are necessary. However, may need to add these later. This would be good to prove out in the public preview.

Since only the identifier is required, this should be removed from the model. This will be cleaner.

There should be some further discussion around id and rawId as it relates to CommunicationIdentifier. This seems to different than the rest of ACS.

• We should follow up with the ACS architecture team (Dominic) to match the usage pattern.

• This model is the base wrapper for an MRI in .NET with a couple of derived classes that helpfully parse it for you, as far as I understand the world

• Use PUT instead of POST -- See the discussion on the PR. It is strongly recommended to use PUT--this creates a much better customer/developer experience. This would also drive consistency across Azure and hide the implementation detail from the customer.

Next Steps

This is not gated for Public Preview, but implement the PUT before GA.

References

Meeting Chat
Meeting Recording