d4a87f8a45
Adds functionality to control the room creation and retrieval responses using the `X-Fields` and `X-Expand` headers. - `X-Fields` allows clients to specify which fields to include in the response, optimizing bandwidth usage. - `X-Expand` allows clients to request the full data of expandable properties, such as `config`, avoiding subsequent GET requests. This change introduces new request validators, service methods, and helper functions to handle the header logic and process the room objects accordingly.
329 lines
14 KiB
YAML
329 lines
14 KiB
YAML
/rooms:
|
|
post:
|
|
operationId: createRoom
|
|
summary: Create a room
|
|
description: >
|
|
Creates a new OpenVidu Meet room.
|
|
The room will be available for participants to join using the generated URLs.
|
|
<br/>
|
|
You can control the response format using custom headers:
|
|
|
|
- `X-Expand`: Include expanded properties (e.g., `config`) instead of stubs
|
|
|
|
- `X-Fields`: Filter which fields to include in the response for efficiency
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/x-fields-header.yaml'
|
|
- $ref: '../components/parameters/x-expand-header.yaml'
|
|
requestBody:
|
|
$ref: '../components/requestBodies/create-room-request.yaml'
|
|
responses:
|
|
'201':
|
|
$ref: '../components/responses/success-create-room.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
get:
|
|
operationId: getRooms
|
|
summary: Get all rooms
|
|
description: |
|
|
Retrieves a paginated list of rooms available in the system.
|
|
You can apply filters to narrow down the results based on specific criteria.
|
|
|
|
By default, the rooms are sorted by creation date in descending order (newest first).
|
|
|
|
> **Note:** If this endpoint is called using the `accessTokenHeader` authentication method,
|
|
> only rooms the authenticated user has access to will be returned.
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-name.yaml'
|
|
- $ref: '../components/parameters/room-status.yaml'
|
|
- $ref: '../components/parameters/room-fields.yaml'
|
|
- $ref: '../components/parameters/expand.yaml'
|
|
- $ref: '../components/parameters/max-items.yaml'
|
|
- $ref: '../components/parameters/next-page-token.yaml'
|
|
- $ref: '../components/parameters/sort-field.yaml'
|
|
- $ref: '../components/parameters/sort-order.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-get-rooms.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
delete:
|
|
operationId: bulkDeleteRooms
|
|
summary: Bulk delete rooms
|
|
description: |
|
|
Delete multiple OpenVidu Meet rooms at once with the specified room IDs.
|
|
|
|
If any of the rooms have active meetings or recordings,
|
|
deletion behavior is determined by the provided `withMeeting` and `withRecordings` deletion policies.
|
|
|
|
Depending on these policies, the rooms may be deleted/closed immediately, scheduled to be deleted/closed once the meetings end,
|
|
or the operation may fail if deletion is not permitted.
|
|
|
|
> **Note:** If this endpoint is called using the `accessTokenHeader` authentication method,
|
|
> only rooms the authenticated user can manage will be deleted.
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-ids.yaml'
|
|
- $ref: '../components/parameters/meeting-deletion-policy.yaml'
|
|
- $ref: '../components/parameters/recordings-deletion-policy.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-bulk-delete-rooms.yaml'
|
|
'400':
|
|
$ref: '../components/responses/error-bulk-delete-rooms.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
/rooms/{roomId}:
|
|
get:
|
|
operationId: getRoom
|
|
summary: Get a room
|
|
description: >
|
|
Retrieves the details of an OpenVidu Meet room with the specified room ID.
|
|
<br/>
|
|
By default, certain large properties like `config` are excluded from the response
|
|
to reduce payload size. These properties are replaced with an expandable stub.
|
|
Use the `expand` parameter to include these properties when needed.
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-id-path.yaml'
|
|
- $ref: '../components/parameters/room-fields.yaml'
|
|
- $ref: '../components/parameters/expand.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-get-room.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-room-not-found.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
delete:
|
|
operationId: deleteRoom
|
|
summary: Delete a room
|
|
description: |
|
|
Deletes the specified OpenVidu Meet room by its room ID.
|
|
|
|
If the room has an active meeting or existing recordings,
|
|
deletion behavior is determined by the provided `withMeeting` and `withRecordings` deletion policies.
|
|
|
|
Depending on these policies, the room may be deleted/closed immediately, scheduled to be deleted/closed once the meeting ends,
|
|
or the operation may fail if deletion is not permitted.
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-id-path.yaml'
|
|
- $ref: '../components/parameters/meeting-deletion-policy.yaml'
|
|
- $ref: '../components/parameters/recordings-deletion-policy.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-room-process-deletion.yaml'
|
|
'202':
|
|
$ref: '../components/responses/success-room-schedule-deletion.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-room-not-found.yaml'
|
|
'409':
|
|
$ref: '../components/responses/error-room-process-deletion.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
/rooms/{roomId}/config:
|
|
get:
|
|
operationId: getRoomConfig
|
|
summary: Get room config
|
|
description: >
|
|
Retrieves the config of an OpenVidu Meet room with the specified room ID.
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-id-path.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-get-room-config.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-room-not-found.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
put:
|
|
operationId: updateRoomConfig
|
|
summary: Update room config
|
|
description: >
|
|
Updates the config of an OpenVidu Meet room with the specified room ID.
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-id-path.yaml'
|
|
requestBody:
|
|
$ref: '../components/requestBodies/update-room-config-request.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-update-room-config.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-room-not-found.yaml'
|
|
'409':
|
|
$ref: '../components/responses/error-room-active-meeting.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
/rooms/{roomId}/status:
|
|
put:
|
|
operationId: updateRoomStatus
|
|
summary: Update room status
|
|
description: >
|
|
Updates the status of an OpenVidu Meet room with the specified room ID.
|
|
This can be used to open or close the room for new participants.
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-id-path.yaml'
|
|
requestBody:
|
|
$ref: '../components/requestBodies/update-room-status-request.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-update-room-status.yaml'
|
|
'202':
|
|
$ref: '../components/responses/success-room-schedule-closure.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-room-not-found.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
/rooms/{roomId}/roles:
|
|
put:
|
|
operationId: updateRoomRoles
|
|
summary: Update roles permissions for a room
|
|
description: |
|
|
Updates the permissions by role for the specified room.
|
|
|
|
You can customize permissions for moderator and/or speaker roles.
|
|
Only specify the permissions you want to change from the current configuration.
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-id-path.yaml'
|
|
requestBody:
|
|
$ref: '../components/requestBodies/update-room-roles-request.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-update-room-roles.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-room-not-found.yaml'
|
|
'409':
|
|
$ref: '../components/responses/error-room-active-meeting.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
/rooms/{roomId}/anonymous:
|
|
put:
|
|
operationId: updateRoomAnonymous
|
|
summary: Update anonymous access config for a room
|
|
description: |
|
|
Updates the anonymous access configuration for the specified room.
|
|
|
|
This allows you to enable or disable anonymous access for specific roles (moderator/speaker).
|
|
tags:
|
|
- OpenVidu Meet - Rooms
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-id-path.yaml'
|
|
requestBody:
|
|
$ref: '../components/requestBodies/update-room-anonymous-request.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-update-room-anonymous.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-room-not-found.yaml'
|
|
'409':
|
|
$ref: '../components/responses/error-room-active-meeting.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|