neoris/openvidu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backend: Add internal API endpoints for managing meetings and getting roles and permissions associated to rooms in OpenAPI specs

Browse Source
This commit is contained in:
juancarmore 2025-04-14 11:31:45 +02:00
parent 8cc81a9ff6
commit 8b87b9ca21
10 changed files with 277 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
backend/openapi/components/responses/internal/error-invalid-room-secret.yaml Normal file
View File

@ -0,0 +1,8 @@
description: Invalid room secret
content:
application/json:
schema:
$ref: ../../schemas/error.yaml
example:
name: 'Room Error'
message: 'The secret "123456"" is not recognized for room "room-123"'

9
backend/openapi/components/responses/internal/success-end-meeting.yaml Normal file
View File

@ -0,0 +1,9 @@
description: Meeting ended successfully
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: 'Meeting ended successfully'

5
backend/openapi/components/responses/internal/success-get-room-role.yaml Normal file
View File

@ -0,0 +1,5 @@
description: Successfully retrieved the room role and associated permissions
content:
application/json:
schema:
$ref: '../../schemas/internal/meet-room-role-permissions.yaml'

52
backend/openapi/components/responses/internal/success-get-room-roles.yaml Normal file
View File

@ -0,0 +1,52 @@
description: Successfully retrieved all roles and associated permissions in a room
content:
application/json:
schema:
type: array
items:
$ref: '../../schemas/internal/meet-room-role-permissions.yaml'
example:
- role: 'moderator'
permissions:
livekit:
roomCreate: true
roomJoin: true
roomList: true
roomRecord: true
roomAdmin: true
room: 'room-123'
ingressAdmin: true
canPublish: true
canSubscribe: true
canPublishData: true
canUpdateOwnMetadata: true
hidden: false
recorder: false
agent: false
openvidu:
canPublishScreen: true
canRecord: true
canChat: true
canChangeVirtualBackground: true
- role: 'publisher'
permissions:
livekit:
roomCreate: false
roomJoin: true
roomList: true
roomRecord: false
roomAdmin: false
room: 'room-123'
ingressAdmin: false
canPublish: true
canSubscribe: true
canPublishData: true
canUpdateOwnMetadata: true
hidden: false
recorder: false
agent: false
openvidu:
canPublishScreen: true
canRecord: false
canChat: true
canChangeVirtualBackground: true

110
backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml Normal file
View File

@ -0,0 +1,110 @@
type: object
properties:
role:
type: string
enum: ['moderator', 'publisher']
description: >
A role that a participant can have in a room.
The role determines the permissions of the participant in the room.
- `moderator`: Can manage the room and its participants.
- `publisher`: Can publish media streams to the room.
example: 'moderator'
permissions:
type: object
properties:
livekit:
type: object
properties:
roomCreate:
type: boolean
description: >
Indicates whether the participant can create a room.
example: true
roomJoin:
type: boolean
description: >
Indicates whether the participant can join a room.
example: true
roomList:
type: boolean
description: >
Indicates whether the participant can list available rooms.
example: true
roomRecord:
type: boolean
description: >
Indicates whether the participant can record a room.
example: true
roomAdmin:
type: boolean
description: >
Indicates whether the participant has administrative privileges in the room.
example: true
room:
type: string
description: >
The ID of the room associated with the participant.
example: roomId
ingressAdmin:
type: boolean
description: >
Indicates whether the participant can manage ingress settings.
example: true
canPublish:
type: boolean
description: >
Indicates whether the participant can publish media streams to the room.
example: true
canSubscribe:
type: boolean
description: >
Indicates whether the participant can subscribe to media streams in the room.
example: true
canPublishData:
type: boolean
description: >
Indicates whether the participant can publish data messages to the room.
example: true
canUpdateOwnMetadata:
type: boolean
description: >
Indicates whether the participant can update their own metadata.
example: true
hidden:
type: boolean
description: >
Indicates whether the participant is hidden in the room.
example: false
recorder:
type: boolean
description: >
Indicates whether the participant is a recorder in the room.
example: false
agent:
type: boolean
description: >
Indicates whether the participant is an agent in the room.
example: false
openvidu:
type: object
properties:
canPublishScreen:
type: boolean
description: >
Indicates whether the participant can publish screen sharing in the room.
example: true
canRecord:
type: boolean
description: >
Indicates whether the participant can record the room.
example: true
canChat:
type: boolean
description: >
Indicates whether the participant can send and receive chat messages in the room.
example: true
canChangeVirtualBackground:
type: boolean
description: >
Indicates whether the participant can change virtual background in the room.
example: true

18
backend/openapi/openvidu-meet-internal-api.yaml
View File

@ -18,8 +18,10 @@ paths:
$ref: './paths/internal/auth.yaml#/~1auth~1profile' $ref: './paths/internal/auth.yaml#/~1auth~1profile'
/rooms/{roomId}: /rooms/{roomId}:
$ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}' $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}'
/rooms/{roomId}/participant-role: /rooms/{roomId}/roles:
$ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1participant-role' $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1roles'
/rooms/{roomId}/roles/{secret}:
$ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1roles~1{secret}'
/recordings: /recordings:
$ref: './paths/internal/recordings.yaml#/~1recordings' $ref: './paths/internal/recordings.yaml#/~1recordings'
/recordings/{recordingId}/stop: /recordings/{recordingId}/stop:
@ -28,12 +30,14 @@ paths:
$ref: './paths/internal/participants.yaml#/~1participants~1token' $ref: './paths/internal/participants.yaml#/~1participants~1token'
/participants/token/refresh: /participants/token/refresh:
$ref: './paths/internal/participants.yaml#/~1participants~1token~1refresh' $ref: './paths/internal/participants.yaml#/~1participants~1token~1refresh'
/participants/{participantName}: /meetings/{roomId}:
$ref: './paths/internal/participants.yaml#/~1participants~1{participantName}' $ref: './paths/internal/meetings.yaml#/~1meetings~1{roomId}'
/meetings/{roomId}/participants/{participantName}:
$ref: './paths/internal/meetings.yaml#/~1meetings~1{roomId}~1participants~1{participantName}'
components: components:
securitySchemes: securitySchemes:
$ref: './components/security.yaml' $ref: components/security.yaml
schemas: schemas:
User: User:
$ref: components/schemas/internal/user.yaml $ref: components/schemas/internal/user.yaml
@ -42,7 +46,9 @@ components:
MeetRoomOptions: MeetRoomOptions:
$ref: components/schemas/meet-room-options.yaml $ref: components/schemas/meet-room-options.yaml
MeetRoomPreferences: MeetRoomPreferences:
$ref: './components/schemas/meet-room-preferences.yaml#/MeetRoomPreferences' $ref: components/schemas/meet-room-preferences.yaml#/MeetRoomPreferences
MeetRoomRoleAndPermissions:
$ref: components/schemas/internal/meet-room-role-permissions.yaml
MeetRecording: MeetRecording:
$ref: components/schemas/meet-recording.yaml $ref: components/schemas/meet-recording.yaml
Error: Error:

49
backend/openapi/paths/internal/meetings.yaml Normal file
View File

@ -0,0 +1,49 @@
/meetings/{roomId}:
delete:
operationId: endMeeting
summary: End a meeting
description: >
Ends a meeting in an OpenVidu Meet room. This will stop all recordings and disconnect all participants.
This endpoint is idempotent. If the meeting is already ended, it will return a success response without any action.
tags:
- Internal API - Meetings
security:
- participantTokenCookie: []
parameters:
- $ref: '../../components/parameters/room-id.yaml'
responses:
'200':
$ref: '../../components/responses/internal/success-end-meeting.yaml'
'401':
$ref: '../../components/responses/unauthorized-error.yaml'
'403':
$ref: '../../components/responses/forbidden-error.yaml'
# '404':
# $ref: '../../components/responses/error-room-not-found.yaml'
'500':
$ref: '../../components/responses/internal-server-error.yaml'
/meetings/{roomId}/participants/{participantName}:
delete:
operationId: disconnectParticipant
summary: Delete a participant from a meeting
description: >
Deletes a participant from an OpenVidu Meet room. This will disconnect the participant from the meeting.
tags:
- Internal API - Meetings
security:
- participantTokenCookie: []
parameters:
- $ref: '../../components/parameters/room-id.yaml'
- $ref: '../../components/parameters/internal/participant-name.yaml'
responses:
'200':
$ref: '../../components/responses/internal/success-delete-participant.yaml'
'401':
$ref: '../../components/responses/unauthorized-error.yaml'
'403':
$ref: '../../components/responses/forbidden-error.yaml'
'404':
$ref: '../../components/responses/internal/error-participant-not-found.yaml'
'500':
$ref: '../../components/responses/internal-server-error.yaml'

29
backend/openapi/paths/internal/participants.yaml
View File

@ -13,6 +13,8 @@
responses: responses:
'200': '200':
$ref: '../../components/responses/internal/success-generate-participant-token.yaml' $ref: '../../components/responses/internal/success-generate-participant-token.yaml'
'400':
$ref: '../../components/responses/internal/error-invalid-room-secret.yaml'
'401': '401':
$ref: '../../components/responses/unauthorized-error.yaml' $ref: '../../components/responses/unauthorized-error.yaml'
'403': '403':
@ -23,7 +25,6 @@
$ref: '../../components/responses/internal/error-participant-already-exists.yaml' $ref: '../../components/responses/internal/error-participant-already-exists.yaml'
'500': '500':
$ref: '../../components/responses/internal-server-error.yaml' $ref: '../../components/responses/internal-server-error.yaml'
/participants/token/refresh: /participants/token/refresh:
post: post:
operationId: refreshParticipantToken operationId: refreshParticipantToken
@ -39,6 +40,8 @@
responses: responses:
'200': '200':
$ref: '../../components/responses/internal/success-generate-participant-token.yaml' $ref: '../../components/responses/internal/success-generate-participant-token.yaml'
'400':
$ref: '../../components/responses/internal/error-invalid-room-secret.yaml'
'401': '401':
$ref: '../../components/responses/unauthorized-error.yaml' $ref: '../../components/responses/unauthorized-error.yaml'
'403': '403':
@ -49,27 +52,3 @@
$ref: '../../components/responses/internal/error-participant-token-still-valid.yaml' $ref: '../../components/responses/internal/error-participant-token-still-valid.yaml'
'500': '500':
$ref: '../../components/responses/internal-server-error.yaml' $ref: '../../components/responses/internal-server-error.yaml'
/participants/{participantName}:
delete:
operationId: disconnectParticipant
summary: Delete a participant from a room
description: >
Deletes a participant from an OpenVidu Meet room.
tags:
- Internal API - Participant
security:
- participantTokenCookie: []
parameters:
- $ref: '../../components/parameters/room-id.yaml'
- $ref: '../../components/parameters/internal/participant-name.yaml'
responses:
'200':
$ref: '../../components/responses/internal/success-delete-participant.yaml'
'401':
$ref: '../../components/responses/unauthorized-error.yaml'
'403':
$ref: '../../components/responses/forbidden-error.yaml'
'404':
$ref: '../../components/responses/internal/error-participant-not-found.yaml'
'500':
$ref: '../../components/responses/internal-server-error.yaml'

42
backend/openapi/paths/internal/rooms.yaml
View File

@ -25,32 +25,42 @@
$ref: '../../components/responses/validation-error.yaml' $ref: '../../components/responses/validation-error.yaml'
'500': '500':
$ref: '../../components/responses/internal-server-error.yaml' $ref: '../../components/responses/internal-server-error.yaml'
/rooms/{roomId}/participant-role: /rooms/{roomId}/roles:
get: get:
operationId: getParticipantRole operationId: getRoomRolesAndPermissions
summary: Get participant role in a room summary: Get room roles and permissions
description: > description: >
Retrieves the role that a participant will have in a specified OpenVidu Meet room when using the URL thant contains the secret token. Retrieves the roles and associated permissions that a participant can have in a specified OpenVidu Meet room.
This endpoint is useful for checking the participant's role before joining the room. tags:
- Internal API - Rooms
parameters:
- $ref: '../../components/parameters/room-id.yaml'
responses:
'200':
$ref: '../../components/responses/internal/success-get-room-roles.yaml'
'404':
$ref: '../../components/responses/error-room-not-found.yaml'
'500':
$ref: '../../components/responses/internal-server-error.yaml'
/rooms/{roomId}/roles/{secret}:
get:
operationId: getRoomRoleAndPermissions
summary: Get room role and permissions
description: >
Retrieves the role and associated permissions that a participant will have in a specified OpenVidu Meet room
when using the URL thant contains the given secret value.
This endpoint is useful for checking the participant's role and permissions before joining the room.
tags: tags:
- Internal API - Rooms - Internal API - Rooms
security:
- accessTokenCookie: []
parameters: parameters:
- $ref: '../../components/parameters/room-id.yaml' - $ref: '../../components/parameters/room-id.yaml'
- $ref: '../../components/parameters/internal/secret.yaml' - $ref: '../../components/parameters/internal/secret.yaml'
responses: responses:
'200': '200':
description: Successfully retrieved participant role $ref: '../../components/responses/internal/success-get-room-role.yaml'
content: '400':
application/json: $ref: '../../components/responses/internal/error-invalid-room-secret.yaml'
schema:
type: string
example: 'moderator'
description: The role that the participant will have in the room.
'404': '404':
$ref: '../../components/responses/error-room-not-found.yaml' $ref: '../../components/responses/error-room-not-found.yaml'
'422':
$ref: '../../components/responses/validation-error.yaml'
'500': '500':
$ref: '../../components/responses/internal-server-error.yaml' $ref: '../../components/responses/internal-server-error.yaml'

2
backend/openapi/tags/tags.yaml
View File

@ -8,5 +8,7 @@
description: Operations related to managing OpenVidu Meet rooms description: Operations related to managing OpenVidu Meet rooms
- name: Internal API - Participant - name: Internal API - Participant
description: Operations related to managing participants in OpenVidu Meet rooms description: Operations related to managing participants in OpenVidu Meet rooms
- name: Internal API - Meetings
description: Operations related to managing meetings in OpenVidu Meet rooms
- name: Internal API - Recordings - name: Internal API - Recordings
description: Operations related to managing OpenVidu Meet recordings description: Operations related to managing OpenVidu Meet recordings