Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

large room updates across the room api and a new guide doc #1799

Merged
merged 10 commits into from
Oct 12, 2023
Merged

large room updates across the room api and a new guide doc #1799

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
a315cef
large room updates across the room api and a new guide doc
mntrspace Oct 10, 2023
5c11588
Update create-large-rooms.mdx
mntrspace Oct 10, 2023
c83e7c3
Update create-large-rooms.mdx
mntrspace Oct 10, 2023
f6d93a6
Update create-large-rooms.mdx
mntrspace Oct 10, 2023
8de3968
Review changes are updated.
mntrspace Oct 11, 2023
5a14398
Update create-large-rooms.mdx
mntrspace Oct 11, 2023
0eaff2b
Update create-large-rooms.mdx
mntrspace Oct 11, 2023
c585704
Update release-notes.mdx
mntrspace Oct 12, 2023
8235598
Update create-large-rooms.mdx
mntrspace Oct 12, 2023
7306031
Update create-large-rooms.mdx
mntrspace Oct 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions docs/server-side/v2/api-reference/Rooms/create-via-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,13 @@ curl --location --request POST 'https://api.100ms.live/v2/rooms' \
"name": "new-room-1662723668",
"enabled": true,
"description": "This is a sample description for the room",
"customer": "627cdddff2e4e30487862ad1",
"customer_id": "627cdddff2e4e30487862ad1",
"app_id":"62510797903d857ab8ec3ba5",
"recording_info": {
"enabled": false
},
"template_id": "63188115d11d6db790c73c60",
"template": "sample-template-name",
"region": "us",
"created_at": "2022-09-09T11:41:08.082Z",
"updated_at": "2022-09-09T11:41:08.074Z"
Expand All @@ -43,23 +45,25 @@ curl --location --request POST 'https://api.100ms.live/v2/rooms' \

## Main Arguments

| Name | Type | Description | Required |
| :------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| name <br/> | `string` | An alias you can assign to 100ms rooms. This is `case-insensitive`. <br/><br/>Accepted characters are `a-z, A-Z, 0-9, and . - : _`. If not provided, this is generated automatically. <br/><br/>**Note**: If `Create room request` is triggered with an existing room name, then the corresponding room ID is returned. | No |
| description <br/> | `string` | A string to describe your room's usage. For example "9PM English Class Batch 2" | No |
| template_id <br/> | `string` | Template ID of template you wish to associate with the room. You can get template ID either from the templates section on the [dashboard](https://dashboard.100ms.live/dashboard) or use the [Template API](../policy/retrieve-a-template). <br/><br/>**Note**: `default template` will be assigned if template is not specified in the `create room request`. | No |
| recording_info <br/> | `object` | Object of type `recording_info`. This object contains information for enabling recording/setting storage location for recordings. <br/><br/>Check the [recording_info arguments](#recording-info-arguments) below for more information. | No |
| region <br/> | `string` | Region in which you want to create a room. <br/><br/> `eu` - European Union <br/><br/> `in` - India <br/><br/> `us` - United States <br/><br/><br/> `auto` Fallback to region of the template (default value) | No |
| Name | Type | Description | Required |
|:---------------------|:----------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------|
| name <br/> | `string` | An alias you can assign to 100ms rooms. This is `case-insensitive`. <br/><br/>Accepted characters are `a-z, A-Z, 0-9, and . - : _`. If not provided, this is generated automatically. <br/><br/>**Note**: If `Create room request` is triggered with an existing room name, then the corresponding room ID is returned. | No |
| description <br/> | `string` | A string to describe your room's usage. For example "9PM English Class Batch 2" | No |
| template_id <br/> | `string` | Template ID of template you wish to associate with the room. You can get template ID either from the templates section on the [dashboard](https://dashboard.100ms.live/dashboard) or use the [Template API](../policy/retrieve-a-template). <br/><br/>**Note**: `default template` will be assigned if template is not specified in the `create room request`. | No |
| recording_info <br/> | `object` | Object of type `recording_info`. This object contains information for enabling recording/setting storage location for recordings. <br/><br/>Check the [recording_info arguments](#recording-info-arguments) below for more information. | No |
| region <br/> | `string` | Region in which you want to create a room. <br/><br/> `eu` - European Union <br/><br/> `in` - India <br/><br/> `us` - United States <br/><br/><br/> `auto` Fallback to region of the template (default value) | No |
| large_room <br/> | `boolean` | Enable this flag if the requirement is to support more than 2500 peers in the room. You are also required to update to latest SDKs to support this functionality. By default, this value is set to `false`. Learn more about it in the [large room creation guide](/server-side/v2/how-to-guides/create-large-rooms). | No |
| size <br/> | `int` | This value is used to define the maximum number of peers expected to be joining the given room. Following are the acceptable ranges: <br/> <br/> With `large_room: false`, Minimum `size` = 0; Maximum `size` = 2500 <br/> <br/> With `large_room: true`, Minimum `size` = 0; Maximum `size` = 20000 | No |

> **Warning:** If you create a room with the name of an existing room, the same room will be updated with the new configuration passed in the request payload. <br/> For example, if the existing room was assigned to template-ABC earlier and in the request payload you've used template-DEF, then template-DEF will be assigned to the existing room.
> **Warning:** If you create a room with the name of an existing room, the same room will be updated with the new configuration passed in the request payload. <br/> For example, if the existing room was assigned to **'template-ABC'** earlier and in the request payload you've used **'template-DEF'**, then **'template-DEF'** will be assigned to the existing room.

## recording_info arguments

> **Note**: This object enables recording and configuring storage during room creation. But we recommend configuring it at a template level through the [Dashboard](https://dashboard.100ms.live/dashboard), where the config validator can help with validating inputs proactively.

| Name | Type | Description | Required |
| :---------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| enabled | `boolean` | Enable SFU recording. Disabled by default. <br/><br/> **Note:** This argument is only applicable to enable/disable [SFU recording](/server-side/v2/Destinations/recording). Refer to [RTMP Streaming & Browser Recording](/server-side/v2/Destinations/rtmp-streaming-and-browser-recording) guide for other options. | No |
| enabled | `boolean` | Enable SFU recording. Disabled by default. <br/><br/> **Note:** This argument is only applicable to enable/disable [SFU recording](/server-side/v2/Destinations/recording). Refer to [RTMP Streaming & Browser Recording](/server-side/v2/api-reference/external-streams/overview) guide for other options. | No |
| upload_info | `object` | Object of type `upload_info`. This object contains information on recordings storage location. <br/><br/>If you want to store recording with 100ms, and not use your own storage (s3/gs/oss), don't add this to the object. <br/><br/>Check the [upload_info object](#upload-info-arguments) below for more information. | No |

`recording_info` in the room acts as an atomic property. It depends on the recording settings defined in a template as below:
Expand Down
4 changes: 3 additions & 1 deletion docs/server-side/v2/api-reference/Rooms/disable-or-enable.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,9 @@ curl --location --request POST 'https://api.100ms.live/v2/rooms/<room_id>' \
"template": "",
"region": "",
"created_at": "2022-09-06T05:08:31.935Z",
"updated_at": "2022-09-08T14:58:25.629819038Z"
"updated_at": "2022-09-08T14:58:25.629819038Z",
"customer": "627cdddff2e4e30487862ad1",
"large_room": false
}
```

Expand Down
7 changes: 5 additions & 2 deletions docs/server-side/v2/api-reference/Rooms/list-rooms.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,21 +38,22 @@ curl --location --request GET 'https://api.100ms.live/v2/rooms' \
"name": "test-room",
"enabled": true,
"description": "This is a test room",
"customer": "627cda********a39291b",
"customer_id": "627cda********a39291b",
"recording_source_template": true,
"template_id": "627cd********784227d3",
"template": "default_createown_e319635a-****-****-****-ae9e95891e31",
"region": "in",
"created_at": "2022-06-29T03:34:30.194Z",
"key": "627***********a39291b:test-room",
"updated_at": "0001-01-01T00:00:00Z"
"large_room": false
},
{
"id": "627cda81********6b077bc33",
"name": "4b2705aa-****-****-****-f470c06d0c03",
"enabled": true,
"description": "This is a test room",
"customer": "627cd********037a39291b",
"customer_id": "627cd********037a39291b",
"recording_source_template": false,
"recording": {
"enabled": false
Expand All @@ -63,6 +64,8 @@ curl --location --request GET 'https://api.100ms.live/v2/rooms' \
"created_at": "2022-05-12T09:59:29.343Z",
"key": "627cda********037a39291b:4b2705aa-****-****-****-f470c06d0c03",
"updated_at": "0001-01-01T00:00:00Z"
"large_room": true,
"size":19000
}
],
"last": "627cda81bd4f3b56b077bc33"
Expand Down
7 changes: 5 additions & 2 deletions docs/server-side/v2/api-reference/Rooms/object.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,19 @@ nav: 2.2
## Object

| Argument | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id | Unique identifier for the room |
| name | Alias for the room |
| enabled | Indicates whether the room is enabled or disabled. <br/><br/> **Note:** If you disable a room, that room can be used for only the current session and users will not be able to join the room later. You can use the [Disable/Enable a room API](/server-side/v2/Rooms/disable-or-enable) with the `enabled` param set to `true` to enable the room again. |
| description | Description for the room |
| customer | Unique identifier for your account |
| customer_id | Unique identifier for your account |
| customer (deprecated) | Unique identifier for your account same as `customer_id` |
| recording_info | Indicates whether the recording is enabled or disabled. <br/><br/> **Note:** `enabled` [argument](/server-side/v2/Rooms/create-via-api#recording-info-arguments) in this object is only applicable to enable/disable [SFU recording](/server-side/v2/Destinations/recording). Refer to [RTMP Streaming & Browser Recording](/server-side/v2/Destinations/rtmp-streaming-and-browser-recording) guide for other options. |
| template_id | Identifier for the template used for this room |
| template (deprecated) | Name for the template (This field is deprecated. To find template name, fetch template using template_id) |
| region | The region in which the room has to be created |
| large_room | Indicates whether the room is capable of supporting large number of peers (>2500) on the conferencing / live streaming setup or not. The client side SDKs are required to be updated to a certain version to support this update. Learn more about enabling large rooms [here](/server-side/v2/how-to-guides/create-large-rooms) |
| size | Indicates the maximum number of peers who can join the given room |

## Postman collection

Expand Down
5 changes: 5 additions & 0 deletions docs/server-side/v2/api-reference/Rooms/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,11 @@ Room APIs will enable you to script actions from the server side based on your b

You can control peer behavior and build interactivity scenarios in an active room with the help of [active room APIs](/server-side/v2/active-rooms/overview).

> **Note on large rooms**
>
> If you wish to create a room which can support large number of peers (>2500), you'll be required to create large rooms which are specially optimised to handle a large count as well as use certain specific client SDKs versions. Follow this [guide](/server-side/v2/how-to-guides/create-large-rooms) on creating large rooms.
>

## Postman collection

You can use our Postman collection to start exploring 100ms APIs.
Expand Down
2 changes: 1 addition & 1 deletion docs/server-side/v2/api-reference/Rooms/retrieve-room.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ curl --location --request GET 'https://api.100ms.live/v2/rooms/<room_id>' \
"name": "sampleroom",
"enabled": true,
"description": "This is sample description for room",
"customer": "627cdddff2e4e30487862ad1",
"customer_id": "627cdddff2e4e30487862ad1",
"recording_source_template": false,
"recording_info": {
"enabled": true,
Expand Down
Loading