diff --git a/backend/openapi/components/responses/internal/error-invalid-room-secret.yaml b/backend/openapi/components/responses/internal/error-invalid-room-secret.yaml new file mode 100644 index 0000000..7934e9f --- /dev/null +++ b/backend/openapi/components/responses/internal/error-invalid-room-secret.yaml @@ -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"' \ No newline at end of file diff --git a/backend/openapi/components/responses/internal/success-end-meeting.yaml b/backend/openapi/components/responses/internal/success-end-meeting.yaml new file mode 100644 index 0000000..2262eea --- /dev/null +++ b/backend/openapi/components/responses/internal/success-end-meeting.yaml @@ -0,0 +1,9 @@ +description: Meeting ended successfully +content: + application/json: + schema: + type: object + properties: + message: + type: string + example: 'Meeting ended successfully' diff --git a/backend/openapi/components/responses/internal/success-get-room-role.yaml b/backend/openapi/components/responses/internal/success-get-room-role.yaml new file mode 100644 index 0000000..fafa704 --- /dev/null +++ b/backend/openapi/components/responses/internal/success-get-room-role.yaml @@ -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' diff --git a/backend/openapi/components/responses/internal/success-get-room-roles.yaml b/backend/openapi/components/responses/internal/success-get-room-roles.yaml new file mode 100644 index 0000000..bb5de30 --- /dev/null +++ b/backend/openapi/components/responses/internal/success-get-room-roles.yaml @@ -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 diff --git a/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml b/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml new file mode 100644 index 0000000..701c8b8 --- /dev/null +++ b/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml @@ -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 diff --git a/backend/openapi/openvidu-meet-internal-api.yaml b/backend/openapi/openvidu-meet-internal-api.yaml index e2424bd..510ddc4 100644 --- a/backend/openapi/openvidu-meet-internal-api.yaml +++ b/backend/openapi/openvidu-meet-internal-api.yaml @@ -18,8 +18,10 @@ paths: $ref: './paths/internal/auth.yaml#/~1auth~1profile' /rooms/{roomId}: $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}' - /rooms/{roomId}/participant-role: - $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1participant-role' + /rooms/{roomId}/roles: + $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: $ref: './paths/internal/recordings.yaml#/~1recordings' /recordings/{recordingId}/stop: @@ -28,12 +30,14 @@ paths: $ref: './paths/internal/participants.yaml#/~1participants~1token' /participants/token/refresh: $ref: './paths/internal/participants.yaml#/~1participants~1token~1refresh' - /participants/{participantName}: - $ref: './paths/internal/participants.yaml#/~1participants~1{participantName}' + /meetings/{roomId}: + $ref: './paths/internal/meetings.yaml#/~1meetings~1{roomId}' + /meetings/{roomId}/participants/{participantName}: + $ref: './paths/internal/meetings.yaml#/~1meetings~1{roomId}~1participants~1{participantName}' components: securitySchemes: - $ref: './components/security.yaml' + $ref: components/security.yaml schemas: User: $ref: components/schemas/internal/user.yaml @@ -42,7 +46,9 @@ components: MeetRoomOptions: $ref: components/schemas/meet-room-options.yaml 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: $ref: components/schemas/meet-recording.yaml Error: diff --git a/backend/openapi/paths/internal/meetings.yaml b/backend/openapi/paths/internal/meetings.yaml new file mode 100644 index 0000000..1269a0a --- /dev/null +++ b/backend/openapi/paths/internal/meetings.yaml @@ -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' diff --git a/backend/openapi/paths/internal/participants.yaml b/backend/openapi/paths/internal/participants.yaml index c243add..3fa564a 100644 --- a/backend/openapi/paths/internal/participants.yaml +++ b/backend/openapi/paths/internal/participants.yaml @@ -13,6 +13,8 @@ responses: '200': $ref: '../../components/responses/internal/success-generate-participant-token.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-room-secret.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': @@ -23,7 +25,6 @@ $ref: '../../components/responses/internal/error-participant-already-exists.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' - /participants/token/refresh: post: operationId: refreshParticipantToken @@ -39,6 +40,8 @@ responses: '200': $ref: '../../components/responses/internal/success-generate-participant-token.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-room-secret.yaml' '401': $ref: '../../components/responses/unauthorized-error.yaml' '403': @@ -49,27 +52,3 @@ $ref: '../../components/responses/internal/error-participant-token-still-valid.yaml' '500': $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' diff --git a/backend/openapi/paths/internal/rooms.yaml b/backend/openapi/paths/internal/rooms.yaml index 1a23060..7b6c341 100644 --- a/backend/openapi/paths/internal/rooms.yaml +++ b/backend/openapi/paths/internal/rooms.yaml @@ -25,32 +25,42 @@ $ref: '../../components/responses/validation-error.yaml' '500': $ref: '../../components/responses/internal-server-error.yaml' -/rooms/{roomId}/participant-role: +/rooms/{roomId}/roles: get: - operationId: getParticipantRole - summary: Get participant role in a room + operationId: getRoomRolesAndPermissions + summary: Get room roles and permissions description: > - Retrieves the role that a participant will have in a specified OpenVidu Meet room when using the URL thant contains the secret token. - This endpoint is useful for checking the participant's role before joining the room. + Retrieves the roles and associated permissions that a participant can have in a specified OpenVidu Meet 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: - Internal API - Rooms - security: - - accessTokenCookie: [] parameters: - $ref: '../../components/parameters/room-id.yaml' - $ref: '../../components/parameters/internal/secret.yaml' responses: '200': - description: Successfully retrieved participant role - content: - application/json: - schema: - type: string - example: 'moderator' - description: The role that the participant will have in the room. + $ref: '../../components/responses/internal/success-get-room-role.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-room-secret.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' diff --git a/backend/openapi/tags/tags.yaml b/backend/openapi/tags/tags.yaml index 54ddf68..3b1b231 100644 --- a/backend/openapi/tags/tags.yaml +++ b/backend/openapi/tags/tags.yaml @@ -8,5 +8,7 @@ description: Operations related to managing OpenVidu Meet rooms - name: Internal API - Participant 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 description: Operations related to managing OpenVidu Meet recordings