diff --git a/backend/openapi/components/headers/accept-ranges.yaml b/backend/openapi/components/headers/accept-ranges.yaml index 8b9b012..a60be2d 100644 --- a/backend/openapi/components/headers/accept-ranges.yaml +++ b/backend/openapi/components/headers/accept-ranges.yaml @@ -1,4 +1,5 @@ -description: Indicates that the server supports range requests for content retrieval +description: > + Specifies that the server allows clients to request specific ranges of content, enabling partial retrieval of resources. schema: type: string example: bytes diff --git a/backend/openapi/components/headers/set-cookie-access-token.yaml b/backend/openapi/components/headers/set-cookie-access-token.yaml index 959a480..4afa363 100644 --- a/backend/openapi/components/headers/set-cookie-access-token.yaml +++ b/backend/openapi/components/headers/set-cookie-access-token.yaml @@ -3,4 +3,4 @@ description: > This cookie is used to authenticate the user in subsequent requests. schema: type: string - example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' +example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' diff --git a/backend/openapi/components/headers/set-cookie-participant-token.yaml b/backend/openapi/components/headers/set-cookie-participant-token.yaml index efb0298..7b3ab7c 100644 --- a/backend/openapi/components/headers/set-cookie-participant-token.yaml +++ b/backend/openapi/components/headers/set-cookie-participant-token.yaml @@ -3,4 +3,4 @@ description: > This cookie is used to authenticate the participant in the room. schema: type: string - example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' +example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' diff --git a/backend/openapi/components/headers/set-cookie-recording-token.yaml b/backend/openapi/components/headers/set-cookie-recording-token.yaml index 6592be1..65e236a 100644 --- a/backend/openapi/components/headers/set-cookie-recording-token.yaml +++ b/backend/openapi/components/headers/set-cookie-recording-token.yaml @@ -3,4 +3,4 @@ description: > This cookie is used to access the recordings in a room. schema: type: string - example: 'OvMeetRecordingToken=token_123456; Path=/; HttpOnly; SameSite=Strict' +example: 'OvMeetRecordingToken=token_123456; Path=/; HttpOnly; SameSite=Strict' diff --git a/backend/openapi/components/headers/set-cookie-refresh-token.yaml b/backend/openapi/components/headers/set-cookie-refresh-token.yaml index 83df563..fc19c5e 100644 --- a/backend/openapi/components/headers/set-cookie-refresh-token.yaml +++ b/backend/openapi/components/headers/set-cookie-refresh-token.yaml @@ -3,4 +3,4 @@ description: > This cookie is used to refresh the access token when it expires. schema: type: string - example: 'OvMeetRefreshToken=token_123456; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict' +example: 'OvMeetRefreshToken=token_123456; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict' diff --git a/backend/openapi/components/parameters/force-deletion.yaml b/backend/openapi/components/parameters/force-deletion.yaml index 1e60a99..fc99fdc 100644 --- a/backend/openapi/components/parameters/force-deletion.yaml +++ b/backend/openapi/components/parameters/force-deletion.yaml @@ -5,5 +5,4 @@ description: > This will immediately disconnect all participants and remove the room. required: false schema: - type: string - example: 'true' + type: boolean diff --git a/backend/openapi/components/parameters/internal/participant-name.yaml b/backend/openapi/components/parameters/internal/participant-name.yaml index e740a12..328867b 100644 --- a/backend/openapi/components/parameters/internal/participant-name.yaml +++ b/backend/openapi/components/parameters/internal/participant-name.yaml @@ -4,4 +4,4 @@ required: true description: The name of the participant. schema: type: string - example: 'Alice' +example: 'Alice' diff --git a/backend/openapi/components/parameters/max-items.yaml b/backend/openapi/components/parameters/max-items.yaml index a26946b..9208cb3 100644 --- a/backend/openapi/components/parameters/max-items.yaml +++ b/backend/openapi/components/parameters/max-items.yaml @@ -1,7 +1,7 @@ name: maxItems in: query required: false -description: The number of rooms per page (default is 10). Maximum is 100. +description: Specifies the maximum number of items to return per page. The default value is 10, and the maximum allowed is 100. schema: type: integer default: 10 diff --git a/backend/openapi/components/parameters/next-page-token.yaml b/backend/openapi/components/parameters/next-page-token.yaml index 18a096c..ee302f4 100644 --- a/backend/openapi/components/parameters/next-page-token.yaml +++ b/backend/openapi/components/parameters/next-page-token.yaml @@ -1,6 +1,6 @@ name: nextPageToken in: query required: false -description: The token to retrieve the next page of elements. +description: A token used for pagination to fetch the next set of items in a multi-page response. schema: type: string diff --git a/backend/openapi/components/parameters/private-access.yaml b/backend/openapi/components/parameters/private-access.yaml index 804392b..fad3520 100644 --- a/backend/openapi/components/parameters/private-access.yaml +++ b/backend/openapi/components/parameters/private-access.yaml @@ -1,8 +1,8 @@ name: privateAcess in: query description: > - Indicates whether the retrieved recording URL should be configured for private access, i.e., the URL will be accessible only to authenticated users. + Specifies if the recording URL should be restricted to private access, + meaning only authenticated users can view or download the recording. required: false schema: - type: string - example: 'true' + type: boolean diff --git a/backend/openapi/components/parameters/recording-fields.yaml b/backend/openapi/components/parameters/recording-fields.yaml index 438ab22..9540d5c 100644 --- a/backend/openapi/components/parameters/recording-fields.yaml +++ b/backend/openapi/components/parameters/recording-fields.yaml @@ -1,9 +1,9 @@ name: fields in: query description: > - The fields to retrieve from the recording. - Comma-separated list of fields to include in the response. + Specifies which fields to include in the response for the recording resource. + Provide a comma-separated list of field names. required: false schema: type: string - example: 'recordingId,roomId' \ No newline at end of file +example: 'recordingId,roomId' diff --git a/backend/openapi/components/parameters/recording-id.yaml b/backend/openapi/components/parameters/recording-id.yaml index 6a12b07..883ea71 100644 --- a/backend/openapi/components/parameters/recording-id.yaml +++ b/backend/openapi/components/parameters/recording-id.yaml @@ -4,4 +4,4 @@ required: true description: The unique identifier of the recording. schema: type: string - example: 'room-123--EG_XYZ--XX445' +example: 'room-123--EG_XYZ--XX445' diff --git a/backend/openapi/components/parameters/recording-ids.yaml b/backend/openapi/components/parameters/recording-ids.yaml index 20ad5bb..72ca2e3 100644 --- a/backend/openapi/components/parameters/recording-ids.yaml +++ b/backend/openapi/components/parameters/recording-ids.yaml @@ -3,9 +3,8 @@ in: query required: true description: > A comma-separated list of recording IDs. -
- Each recording ID should be in the format 'roomId--egressId--uid' + Each recording ID must follow the format: `{roomId}--{egressId}--{uid}`. schema: type: string - example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446' +example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446' diff --git a/backend/openapi/components/parameters/recording-range.yaml b/backend/openapi/components/parameters/recording-range.yaml index fd40c4c..3babb7f 100644 --- a/backend/openapi/components/parameters/recording-range.yaml +++ b/backend/openapi/components/parameters/recording-range.yaml @@ -1,11 +1,14 @@ name: Range in: header required: false -description: > - This endpoint accepts a `Range` header to specify the byte range of the recording file to be streamed. - The format of the `Range` header should be `bytes=start-end`, where `start` is required and `end` is optional. - For example, - - `bytes=0-1023` to request the first 1024 bytes of the file. - - `bytes=1000-` to request from byte 1000 to the end of the file. +description: | + This endpoint supports the `Range` header to request a specific byte range of the recording file. + Use the format `bytes=start-end`, where `start` is the starting byte (required) and `end` is the ending byte (optional). + + Examples: + - `bytes=0-1023`: Requests bytes 0 through 1023 (first 1024 bytes). + - `bytes=1000-`: Requests from byte 1000 to the end of the file. + + This allows efficient partial downloads and resume capabilities for large files. schema: type: string diff --git a/backend/openapi/components/parameters/recording-secret.yaml b/backend/openapi/components/parameters/recording-secret.yaml index 811b115..00a8670 100644 --- a/backend/openapi/components/parameters/recording-secret.yaml +++ b/backend/openapi/components/parameters/recording-secret.yaml @@ -1,6 +1,7 @@ name: secret in: query required: false -description: The secret value used to access the recording when sharing a recording link. +description: > + Optional secret value that must be provided to access the recording via a shared link, enhancing security for shared recordings. schema: type: string diff --git a/backend/openapi/components/parameters/recording-status.yaml b/backend/openapi/components/parameters/recording-status.yaml new file mode 100644 index 0000000..ddd39b6 --- /dev/null +++ b/backend/openapi/components/parameters/recording-status.yaml @@ -0,0 +1,19 @@ +name: status +in: query +required: false +description: | + Filter recordings by their status. + + You can provide multiple statuses as a comma-separated list (e.g., `status=ACTIVE,FAILED`). + + > ⚠️ **Note:** Using this filter may impact performance for large datasets. +schema: + type: string + enum: + - STARTING + - ACTIVE + - ENDING + - COMPLETE + - FAILED + - ABORTED + - LIMIT_REACHED diff --git a/backend/openapi/components/parameters/room-fields.yaml b/backend/openapi/components/parameters/room-fields.yaml index 92d8668..3244bf9 100644 --- a/backend/openapi/components/parameters/room-fields.yaml +++ b/backend/openapi/components/parameters/room-fields.yaml @@ -1,9 +1,9 @@ name: fields in: query description: > - The fields to retrieve from the room. - Comma-separated list of fields to include in the response. + Specifies which fields to include in the response for the room resource. + Provide a comma-separated list of field names. required: false schema: type: string - example: 'roomId,moderatorRoomUrl' +example: 'roomId,moderatorRoomUrl' diff --git a/backend/openapi/components/parameters/room-id-path.yaml b/backend/openapi/components/parameters/room-id-path.yaml index 2f1de92..58405e5 100644 --- a/backend/openapi/components/parameters/room-id-path.yaml +++ b/backend/openapi/components/parameters/room-id-path.yaml @@ -4,4 +4,4 @@ required: true description: The unique identifier of the room. schema: type: string - example: 'room-123' +example: 'room-123' diff --git a/backend/openapi/components/parameters/room-id-query.yaml b/backend/openapi/components/parameters/room-id-query.yaml index f110244..c27c602 100644 --- a/backend/openapi/components/parameters/room-id-query.yaml +++ b/backend/openapi/components/parameters/room-id-query.yaml @@ -1,7 +1,9 @@ name: roomId in: query required: false -description: The unique identifier of the room. Specify the room ID to filter recordings by their associated room. +description: > + The unique identifier for the room. + Use this parameter to filter recordings and retrieve only those associated with the specified room ID. schema: type: string - example: 'room-123' +example: 'room-123' diff --git a/backend/openapi/components/parameters/room-ids.yaml b/backend/openapi/components/parameters/room-ids.yaml index fca8af8..2e32fad 100644 --- a/backend/openapi/components/parameters/room-ids.yaml +++ b/backend/openapi/components/parameters/room-ids.yaml @@ -1,7 +1,9 @@ name: roomIds in: query required: true -description: A comma-separated list of room IDs to delete. +description: > + Comma-separated list of room IDs to delete. + Each ID should correspond to an existing room. schema: type: string - example: 'room-123,room-456' +example: 'room-123,room-456' diff --git a/backend/openapi/components/parameters/x-signature.yaml b/backend/openapi/components/parameters/x-signature.yaml index b935e28..899fe8e 100644 --- a/backend/openapi/components/parameters/x-signature.yaml +++ b/backend/openapi/components/parameters/x-signature.yaml @@ -2,7 +2,6 @@ name: x-signature in: header description: > HMAC-SHA256 signature of the request body, created using your webhook secret. - Use this to verify the webhook came from OpenVidu Meet and wasn't tampered with. required: true schema: diff --git a/backend/openapi/components/parameters/x-timestamp.yaml b/backend/openapi/components/parameters/x-timestamp.yaml index 7208875..f183bcc 100644 --- a/backend/openapi/components/parameters/x-timestamp.yaml +++ b/backend/openapi/components/parameters/x-timestamp.yaml @@ -2,9 +2,7 @@ name: x-timestamp in: header description: > Unix timestamp (in seconds) when the webhook was sent. - Can be used to validate webhook age and prevent replay attacks. required: true schema: type: string - example: '1697030400000' diff --git a/backend/openapi/components/requestBodies/create-room-request.yaml b/backend/openapi/components/requestBodies/create-room-request.yaml index 6ae8110..12236bb 100644 --- a/backend/openapi/components/requestBodies/create-room-request.yaml +++ b/backend/openapi/components/requestBodies/create-room-request.yaml @@ -1,4 +1,4 @@ -description: Room creation details +description: Room creation options required: true content: application/json: diff --git a/backend/openapi/components/requestBodies/internal/start-recording-request.yaml b/backend/openapi/components/requestBodies/internal/start-recording-request.yaml index 504643f..204f377 100644 --- a/backend/openapi/components/requestBodies/internal/start-recording-request.yaml +++ b/backend/openapi/components/requestBodies/internal/start-recording-request.yaml @@ -1,4 +1,4 @@ -description: Recording details +description: Room to record required: true content: application/json: diff --git a/backend/openapi/components/requestBodies/internal/update-room-request.yaml b/backend/openapi/components/requestBodies/internal/update-room-request.yaml index 77e628e..2d7f424 100644 --- a/backend/openapi/components/requestBodies/internal/update-room-request.yaml +++ b/backend/openapi/components/requestBodies/internal/update-room-request.yaml @@ -1,4 +1,4 @@ -description: Room update details +description: New room preferences content: application/json: schema: diff --git a/backend/openapi/components/requestBodies/internal/update-security-preferences.yaml b/backend/openapi/components/requestBodies/internal/update-security-preferences.yaml index 042c034..572b973 100644 --- a/backend/openapi/components/requestBodies/internal/update-security-preferences.yaml +++ b/backend/openapi/components/requestBodies/internal/update-security-preferences.yaml @@ -1,4 +1,4 @@ -description: Security preferences +description: New security preferences required: true content: application/json: diff --git a/backend/openapi/components/requestBodies/internal/update-webhooks-preferences.yaml b/backend/openapi/components/requestBodies/internal/update-webhooks-preferences.yaml index 365ee53..a656cc9 100644 --- a/backend/openapi/components/requestBodies/internal/update-webhooks-preferences.yaml +++ b/backend/openapi/components/requestBodies/internal/update-webhooks-preferences.yaml @@ -1,4 +1,4 @@ -description: Webhooks preferences +description: New webhooks preferences required: true content: application/json: diff --git a/backend/openapi/components/responses/internal/error-recording-not-active.yaml b/backend/openapi/components/responses/internal/error-recording-not-active.yaml index 8401898..7d27e4b 100644 --- a/backend/openapi/components/responses/internal/error-recording-not-active.yaml +++ b/backend/openapi/components/responses/internal/error-recording-not-active.yaml @@ -1,4 +1,4 @@ -description: Conflict — The recording is in `STARTING` state or already stopped +description: Conflict — The recording is starting or already stopped content: application/json: schema: diff --git a/backend/openapi/components/responses/internal/success-delete-participant.yaml b/backend/openapi/components/responses/internal/success-delete-participant.yaml index f2a9577..833475a 100644 --- a/backend/openapi/components/responses/internal/success-delete-participant.yaml +++ b/backend/openapi/components/responses/internal/success-delete-participant.yaml @@ -1,4 +1,4 @@ -description: Successfully disconnect the participant +description: Successfully disconnected the participant content: application/json: schema: diff --git a/backend/openapi/components/responses/internal/success-start-recording.yaml b/backend/openapi/components/responses/internal/success-start-recording.yaml index 9a92f79..c5c60ca 100644 --- a/backend/openapi/components/responses/internal/success-start-recording.yaml +++ b/backend/openapi/components/responses/internal/success-start-recording.yaml @@ -15,4 +15,4 @@ headers: schema: type: string format: uri - example: https://your-api.com/meet/internal-api/v1/recordings/room-123--EG_XYZ--XX445 + example: https://your-api.com/internal-api/v1/recordings/room-123--EG_XYZ--XX445 diff --git a/backend/openapi/components/responses/internal/success-stop-recording.yaml b/backend/openapi/components/responses/internal/success-stop-recording.yaml index ce8242a..21109a8 100644 --- a/backend/openapi/components/responses/internal/success-stop-recording.yaml +++ b/backend/openapi/components/responses/internal/success-stop-recording.yaml @@ -4,7 +4,7 @@ headers: description: The URL to retrieve the recording details schema: type: string - example: 'https://openvidu.example.com/meet/api/v1/recordings/room-123--EG_XYZ--XX445' + example: 'https://openvidu.example.com/api/v1/recordings/room-123--EG_XYZ--XX445' content: application/json: schema: diff --git a/backend/openapi/components/responses/internal/success-user-login.yaml b/backend/openapi/components/responses/internal/success-user-login.yaml index ad06993..57d6b6f 100644 --- a/backend/openapi/components/responses/internal/success-user-login.yaml +++ b/backend/openapi/components/responses/internal/success-user-login.yaml @@ -2,7 +2,7 @@ description: Successfully logged in headers: Set-Cookie: $ref: '../../headers/set-cookie-access-token.yaml' - Set-Cookie-Refresh: + Set-Cookie*: $ref: '../../headers/set-cookie-refresh-token.yaml' content: application/json: diff --git a/backend/openapi/components/responses/internal/success-user-logout.yaml b/backend/openapi/components/responses/internal/success-user-logout.yaml index c2964f3..d4ce038 100644 --- a/backend/openapi/components/responses/internal/success-user-logout.yaml +++ b/backend/openapi/components/responses/internal/success-user-logout.yaml @@ -1,13 +1,11 @@ description: Successfully logged out headers: Set-Cookie: + description: > + Clears the access and refresh token cookie. schema: type: string - example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict' - Set-Cookie-Refresh: - schema: - type: string - example: 'OvMeetRefreshToken=; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict' + example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict' content: application/json: schema: diff --git a/backend/openapi/components/responses/pro-feature-error.yaml b/backend/openapi/components/responses/pro-feature-error.yaml index ad61839..0757f1c 100644 --- a/backend/openapi/components/responses/pro-feature-error.yaml +++ b/backend/openapi/components/responses/pro-feature-error.yaml @@ -1,4 +1,4 @@ -description: PRO Feature Error +description: PRO feature content: application/json: schema: diff --git a/backend/openapi/components/responses/success-bulk-delete-recordings.yaml b/backend/openapi/components/responses/success-bulk-delete-recordings.yaml index 1bfda26..a91abb3 100644 --- a/backend/openapi/components/responses/success-bulk-delete-recordings.yaml +++ b/backend/openapi/components/responses/success-bulk-delete-recordings.yaml @@ -36,14 +36,14 @@ content: - recordingId: 'room-123--EG_XYZ--XX447' error: 'Recording not found' - recordingId: 'room-123--EG_XYZ--XX448' - error: 'Access denied for deletion' + error: 'Recording in progress' no_deletion_performed: summary: No recordings were deleted value: deleted: [] notDeleted: - - recordingId: 'room-123--EG_XYZ--XX445' - error: 'Recording not found' - - recordingId: 'room-123--EG_ZYX--XX446' + - recordingId: 'room-123--EG_XYZ--XX447' error: 'Recording not found' + - recordingId: 'room-123--EG_ZYX--XX448' + error: 'Recording in progress' diff --git a/backend/openapi/components/responses/success-bulk-delete-rooms.yaml b/backend/openapi/components/responses/success-bulk-delete-rooms.yaml index e87609c..8f263cd 100644 --- a/backend/openapi/components/responses/success-bulk-delete-rooms.yaml +++ b/backend/openapi/components/responses/success-bulk-delete-rooms.yaml @@ -15,7 +15,9 @@ content: type: array items: type: string - description: List of rooms that were marked for deletion but not actually deleted. The rooms will be deleted when all participants leave the room. + description: >- + List of rooms that were marked for deletion but not actually deleted. + These rooms will be deleted when all participants leave. example: deleted: - 'room-123' diff --git a/backend/openapi/components/responses/success-create-room.yaml b/backend/openapi/components/responses/success-create-room.yaml index 3215f44..d746f6c 100644 --- a/backend/openapi/components/responses/success-create-room.yaml +++ b/backend/openapi/components/responses/success-create-room.yaml @@ -9,4 +9,4 @@ headers: schema: type: string format: uri - example: https://your-api.com/meet/api/v1/rooms/room-id-123 + example: https://your-api.com/api/v1/rooms/room-123 diff --git a/backend/openapi/components/responses/success-get-recording-url.yaml b/backend/openapi/components/responses/success-get-recording-url.yaml index 44940a2..4d11f5d 100644 --- a/backend/openapi/components/responses/success-get-recording-url.yaml +++ b/backend/openapi/components/responses/success-get-recording-url.yaml @@ -1,4 +1,4 @@ -description: Successfully retrieved the recording URL. +description: Successfully retrieved the recording URL content: application/json: schema: @@ -7,5 +7,5 @@ content: url: type: string format: uri - description: URL to access the recording media. - example: https://example.com/meet/api/v1/recordings/room-123--EG_XYZ--XX445/media?secret=abc123 + description: URL to access the recording. + example: https://example.com/recording/room-123--EG_XYZ--XX445?secret=abc123 diff --git a/backend/openapi/components/responses/success-get-recording.yaml b/backend/openapi/components/responses/success-get-recording.yaml index fa28bda..3c60337 100644 --- a/backend/openapi/components/responses/success-get-recording.yaml +++ b/backend/openapi/components/responses/success-get-recording.yaml @@ -1,4 +1,4 @@ -description: Successfully retrieved the recording. +description: Successfully retrieved the recording content: application/json: schema: diff --git a/backend/openapi/components/responses/success-get-room.yaml b/backend/openapi/components/responses/success-get-room.yaml index 2e21f11..f00fd5c 100644 --- a/backend/openapi/components/responses/success-get-room.yaml +++ b/backend/openapi/components/responses/success-get-room.yaml @@ -18,8 +18,8 @@ content: enabled: false virtualBackgroundPreferences: enabled: true - moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' + moderatorURL: 'http://localhost:6080/room/room-123?secret=123456' + publisherURL: 'http://localhost:6080/room/room-123?secret=654321' fields=roomId: summary: Response with only the roomId @@ -44,5 +44,5 @@ content: fields=moderatorURL,publisherURL: summary: Response containing only moderator and publisher URLs value: - moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' + moderatorURL: 'http://localhost:6080/room/room-123?secret=123456' + publisherURL: 'http://localhost:6080/room/room-123?secret=654321' diff --git a/backend/openapi/components/responses/success-get-rooms.yaml b/backend/openapi/components/responses/success-get-rooms.yaml index ff4276a..c25be43 100644 --- a/backend/openapi/components/responses/success-get-rooms.yaml +++ b/backend/openapi/components/responses/success-get-rooms.yaml @@ -27,8 +27,8 @@ content: enabled: false virtualBackgroundPreferences: enabled: true - moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' + moderatorURL: 'http://localhost:6080/room/room-123?secret=123456' + publisherURL: 'http://localhost:6080/room/room-123?secret=654321' - roomId: 'room-456' roomIdPrefix: 'room' creationDate: 1620001000000 @@ -40,8 +40,8 @@ content: enabled: true virtualBackgroundPreferences: enabled: false - moderatorURL: 'http://localhost:6080/room/room-456/?secret=789012' - publisherURL: 'http://localhost:6080/room/room-456/?secret=210987' + moderatorURL: 'http://localhost:6080/room/room-456?secret=789012' + publisherURL: 'http://localhost:6080/room/room-456?secret=210987' pagination: isTruncated: false maxItems: 10 @@ -90,10 +90,10 @@ content: summary: Response containing only moderator and publisher URLs value: rooms: - - moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456' - publisherURL: 'http://localhost:6080/room/room-123/?secret=654321' - - moderatorURL: 'http://localhost:6080/room/room-456/?secret=789012' - publisherURL: 'http://localhost:6080/room/room-456/?secret=210987' + - moderatorURL: 'http://localhost:6080/room/room-123?secret=123456' + publisherURL: 'http://localhost:6080/room/room-123?secret=654321' + - moderatorURL: 'http://localhost:6080/room/room-456?secret=789012' + publisherURL: 'http://localhost:6080/room/room-456?secret=210987' pagination: isTruncated: false maxItems: 10 diff --git a/backend/openapi/components/responses/success-rooms-marked-for-deletion.yaml b/backend/openapi/components/responses/success-rooms-marked-for-deletion.yaml index 264a401..36509b1 100644 --- a/backend/openapi/components/responses/success-rooms-marked-for-deletion.yaml +++ b/backend/openapi/components/responses/success-rooms-marked-for-deletion.yaml @@ -1,5 +1,5 @@ description: > - All specified rooms were marked error for deletion (due to active participants) + All specified rooms were marked for deletion (due to active participants) and will be removed once all participants leave. content: application/json: diff --git a/backend/openapi/components/responses/validation-error.yaml b/backend/openapi/components/responses/validation-error.yaml index 2ffee30..5670c6e 100644 --- a/backend/openapi/components/responses/validation-error.yaml +++ b/backend/openapi/components/responses/validation-error.yaml @@ -1,4 +1,4 @@ -description: Unprocessable Entity — Invalid request body +description: Unprocessable Entity — Invalid request content: application/json: schema: diff --git a/backend/openapi/components/responses/webhook-success.yaml b/backend/openapi/components/responses/webhook-success.yaml index 9eb0dc3..26a84f0 100644 --- a/backend/openapi/components/responses/webhook-success.yaml +++ b/backend/openapi/components/responses/webhook-success.yaml @@ -1,7 +1,7 @@ -description: > - Webhook received and processed successfully. +description: | + Webhook received and processed successfully. - Important: Webhook endpoints must return HTTP 200 OK promptly to acknowledge receipt. - Any processing should be done asynchronously after responding. - - Non-200 responses or timeouts will trigger retries according to the webhook delivery policy. \ No newline at end of file + > **Important:** Webhook endpoints must return HTTP 200 OK promptly to acknowledge receipt. + > Any processing should be done asynchronously after responding. + > + > Non-200 responses or timeouts will trigger retries according to the webhook delivery policy. diff --git a/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml b/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml index e304b96..fcc0a4a 100644 --- a/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml +++ b/backend/openapi/components/schemas/internal/meet-room-role-permissions.yaml @@ -23,8 +23,7 @@ properties: room: type: string description: > - The ID of the room associated with the participant. - example: roomId + Unique identifier of the room to which the participant is assigned. canPublish: type: boolean description: > @@ -61,5 +60,5 @@ properties: canChangeVirtualBackground: type: boolean description: > - Indicates whether the participant can change virtual background in the room. + Indicates whether the participant can change their own virtual background. example: true diff --git a/backend/openapi/components/schemas/internal/security-preferences.yaml b/backend/openapi/components/schemas/internal/security-preferences.yaml index 0889191..777cc45 100644 --- a/backend/openapi/components/schemas/internal/security-preferences.yaml +++ b/backend/openapi/components/schemas/internal/security-preferences.yaml @@ -16,7 +16,9 @@ AuthenticationPreferences: - single-user default: single-user example: single-user - description: The authentication method to use. + description: | + Specifies the authentication method used to access the application. + - `single-user`: Only one user account exists, which has administrative privileges and is used for all access. authModeToAccessRoom: type: string enum: @@ -25,4 +27,8 @@ AuthenticationPreferences: - all_users default: none example: none - description: The authentication mode to access a room. + description: | + Specifies who is required to authenticate before accessing a room: + - `none`: No authentication required. + - `moderators_only`: Only moderators need to authenticate. + - `all_users`: All users must authenticate. diff --git a/backend/openapi/components/schemas/internal/user.yaml b/backend/openapi/components/schemas/internal/user.yaml index 706d401..3bdae21 100644 --- a/backend/openapi/components/schemas/internal/user.yaml +++ b/backend/openapi/components/schemas/internal/user.yaml @@ -8,5 +8,6 @@ properties: type: array items: type: string + enum: ['admin', 'user'] example: ['admin', 'user'] description: A list of roles assigned to the authenticated user. diff --git a/backend/openapi/components/schemas/internal/webhooks-preferences.yaml b/backend/openapi/components/schemas/internal/webhooks-preferences.yaml index b2686ee..42c71ac 100644 --- a/backend/openapi/components/schemas/internal/webhooks-preferences.yaml +++ b/backend/openapi/components/schemas/internal/webhooks-preferences.yaml @@ -6,5 +6,6 @@ properties: description: Indicates whether webhooks are enabled or disabled. url: type: string + format: uri example: 'https://example.com/webhook' description: The URL to which webhooks will be sent. This is only mandatory if webhooks are enabled. diff --git a/backend/openapi/components/schemas/meet-pagination.yaml b/backend/openapi/components/schemas/meet-pagination.yaml index b992009..adec2c0 100644 --- a/backend/openapi/components/schemas/meet-pagination.yaml +++ b/backend/openapi/components/schemas/meet-pagination.yaml @@ -3,13 +3,13 @@ properties: isTruncated: type: boolean description: > - Indicates if there are more elements to retrieve. - If true, use the `nextPageToken` to fetch the next set of elements. + Indicates if there are more items to retrieve. + If true, use the `nextPageToken` to fetch the next set of items. nextPageToken: type: [string, 'null'] - description: The token to retrieve the next page of elements. + description: The token to retrieve the next page of items. maxItems: type: integer description: > - Maximum number of elements returned in a single response page. + Maximum number of items returned in a single response page. Corresponds to the `maxItems` query parameter in the request. diff --git a/backend/openapi/components/schemas/meet-room-options.yaml b/backend/openapi/components/schemas/meet-room-options.yaml index 60d88ab..adc0a82 100644 --- a/backend/openapi/components/schemas/meet-room-options.yaml +++ b/backend/openapi/components/schemas/meet-room-options.yaml @@ -3,15 +3,14 @@ properties: autoDeletionDate: type: [number, 'null'] example: 1900000000000 - description: > - The date and time when the room will be deleted (must be one hour in the future or more) represented in milliseconds since the Unix epoch. + description: | + The timestamp (in milliseconds since the Unix epoch) specifying when the room will be automatically deleted. + This must be at least one hour in the future. - After this date, the room will be automatically deleted and no new participants can join. + After this time, the room is closed to new participants and scheduled for deletion. + It will be removed after the last participant leaves (graceful deletion). - If this value is set and the date has already passed, the room is marked for deletion but will only be removed after the last - participant leaves ("graceful deletion"). - - If this value is not defined, the room will exist indefinitely until manually deleted. + If not set, the room remains active until manually deleted. roomIdPrefix: type: string example: 'room' diff --git a/backend/openapi/components/schemas/meet-room.yaml b/backend/openapi/components/schemas/meet-room.yaml index 9beadb6..5f169d7 100644 --- a/backend/openapi/components/schemas/meet-room.yaml +++ b/backend/openapi/components/schemas/meet-room.yaml @@ -18,15 +18,14 @@ properties: autoDeletionDate: type: [number, 'null'] example: 1900000000000 - description: > - The date and time when the room will be deleted (must be one hour in the future or more) represented in milliseconds since the Unix epoch. + description: | + The timestamp (in milliseconds since the Unix epoch) specifying when the room will be automatically deleted. + This must be at least one hour in the future. - After this date, the room will be automatically deleted and no new participants can join. + After this time, the room is closed to new participants and scheduled for deletion. + It will be removed after the last participant leaves (graceful deletion). - If this value is set and the date has already passed, the room is marked for deletion but will only be removed after the last - participant leaves ("graceful deletion"). - - If this value is not defined, the room will exist indefinitely until manually deleted. + If not set, the room remains active until manually deleted. preferences: $ref: meet-room-preferences.yaml#/MeetRoomPreferences description: The preferences for the room. @@ -38,13 +37,13 @@ properties: # this limit, new participants will not be allowed to join. moderatorURL: type: string - example: 'http://localhost:6080/room/room-123/?secret=123456' + example: 'http://localhost:6080/room/room-123?secret=123456' description: > - The URL for the moderator to join the room. The moderator has special permissions to manage the + The URL for the moderator participants to join the room. The moderator role has special permissions to manage the room and participants. publisherURL: type: string - example: 'http://localhost:6080/room/room-123/?secret=654321' + example: 'http://localhost:6080/room/room-123?secret=654321' description: > - The URL for the publisher to join the room. The publisher has permissions to publish audio and + The URL for the publisher participants to join the room. The publisher role has permissions to publish audio and video streams to the room. diff --git a/backend/openapi/components/schemas/webhook-base-event.yaml b/backend/openapi/components/schemas/webhook-base-event.yaml index 181dd6c..98a38fc 100644 --- a/backend/openapi/components/schemas/webhook-base-event.yaml +++ b/backend/openapi/components/schemas/webhook-base-event.yaml @@ -1,17 +1,17 @@ type: object required: - - creationDate - - event - - data + - creationDate + - event + - data properties: - creationDate: - type: number - description: The date when the event was created (milliseconds since the Unix epoch). - example: 1620000000000 - event: - type: string - description: Event type identifier. - example: webhookEvent - data: - type: object - description: The data associated with the event. \ No newline at end of file + creationDate: + type: number + description: The date when the event was created (milliseconds since the Unix epoch). + example: 1620000000000 + event: + type: string + description: Event type identifier. + example: webhookEvent + data: + type: object + description: The data associated with the event. diff --git a/backend/openapi/components/security.yaml b/backend/openapi/components/security.yaml index 1a367f2..ef169cc 100644 --- a/backend/openapi/components/security.yaml +++ b/backend/openapi/components/security.yaml @@ -15,7 +15,7 @@ refreshTokenCookie: name: OvMeetRefreshToken in: cookie description: > - The JWT token to refresh the access token when it expires. This token is used to obtain a new access token. + The JWT token to refresh the access token when it expires.. participantTokenCookie: type: apiKey name: OvMeetParticipantToken diff --git a/backend/openapi/openvidu-meet-api.yaml b/backend/openapi/openvidu-meet-api.yaml index 72d2a3a..29bd27f 100644 --- a/backend/openapi/openvidu-meet-api.yaml +++ b/backend/openapi/openvidu-meet-api.yaml @@ -26,8 +26,6 @@ paths: components: securitySchemes: $ref: './components/security.yaml' - # responses: - # $ref: './components/responses.yaml' schemas: MeetRoom: $ref: components/schemas/meet-room.yaml diff --git a/backend/openapi/paths/internal/auth.yaml b/backend/openapi/paths/internal/auth.yaml index f7b31b5..267d71b 100644 --- a/backend/openapi/paths/internal/auth.yaml +++ b/backend/openapi/paths/internal/auth.yaml @@ -27,28 +27,11 @@ - Internal API - Authentication responses: '200': - description: Successfully logged out - headers: - Set-Cookie: - schema: - type: string - example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict' - Set-Cookie-Refresh: - schema: - type: string - example: 'OvMeetRefreshToken=; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict' - content: - application/json: - schema: - type: object - properties: - message: - type: string - example: 'Logout successful' + $ref: '../../components/responses/internal/success-user-logout.yaml' /auth/refresh: post: operationId: refreshAccessToken - summary: Refresh the access token + summary: Refresh access token description: > Refreshes the access token using the refresh token. The new access token is returned in a cookie. @@ -68,10 +51,11 @@ post: operationId: createApiKey summary: Create a new API key - description: > - Creates a new API key. Only one API key can be created in the system. - If an API key already exists, it will be replaced with the new one. - The API key is returned in the response. + description: | + Creates a new API key, returning it in the response. + + > **Note:** Only one API key can be created in the system. + > If an API key already exists, it will be replaced with the new one. tags: - Internal API - Authentication security: @@ -84,8 +68,11 @@ get: operationId: getApiKeys summary: Get API keys - description: > + description: | Retrieves the existing API keys. + + > **Note:** Only one API key can exist in the system. + > If no API key exists, an empty array will be returned. tags: - Internal API - Authentication security: @@ -106,9 +93,6 @@ - accessTokenCookie: [] responses: '204': - description: Successfully deleted the API key + description: Successfully deleted the API key. No content is returned. '500': $ref: '../../components/responses/internal-server-error.yaml' - - - diff --git a/backend/openapi/paths/internal/global-preferences.yaml b/backend/openapi/paths/internal/global-preferences.yaml index c182b95..add6233 100644 --- a/backend/openapi/paths/internal/global-preferences.yaml +++ b/backend/openapi/paths/internal/global-preferences.yaml @@ -45,7 +45,7 @@ operationId: testWebhookUrl summary: Test webhook URL description: > - Tests the provided webhook URL to ensure it is reachable and valid. + Tests the provided webhook URL to ensure it is valid and reachable. tags: - Internal API - Global Preferences requestBody: diff --git a/backend/openapi/paths/internal/meetings.yaml b/backend/openapi/paths/internal/meetings.yaml index c087c9a..3614c8f 100644 --- a/backend/openapi/paths/internal/meetings.yaml +++ b/backend/openapi/paths/internal/meetings.yaml @@ -2,8 +2,8 @@ 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. + description: | + Ends the current 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: @@ -29,9 +29,9 @@ /meetings/{roomId}/participants/{participantName}: delete: operationId: disconnectParticipant - summary: Delete a participant from a meeting + summary: Kick a participant from a meeting description: > - Deletes a participant from an OpenVidu Meet room. This will disconnect the participant from the meeting. + Kicks a participant from the current meeting in an OpenVidu Meet room. tags: - Internal API - Meetings security: diff --git a/backend/openapi/paths/internal/participants.yaml b/backend/openapi/paths/internal/participants.yaml index 59d3783..a1c42b4 100644 --- a/backend/openapi/paths/internal/participants.yaml +++ b/backend/openapi/paths/internal/participants.yaml @@ -1,7 +1,7 @@ /participants/token: post: operationId: generateParticipantToken - summary: Generate a token for a participant + summary: Generate token for participant description: > Generates a token for a participant to join an OpenVidu Meet room. tags: @@ -30,7 +30,7 @@ /participants/token/refresh: post: operationId: refreshParticipantToken - summary: Refresh a token for a participant + summary: Refresh token for participant description: > Refresh a token for a participant in an OpenVidu Meet room. tags: diff --git a/backend/openapi/paths/internal/recordings.yaml b/backend/openapi/paths/internal/recordings.yaml index ec92ab0..3a20e66 100644 --- a/backend/openapi/paths/internal/recordings.yaml +++ b/backend/openapi/paths/internal/recordings.yaml @@ -35,9 +35,10 @@ post: operationId: stopRecording summary: Stop a recording - description: > + description: | Stops a recording with the specified recording ID. - The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned. + + > **Note:** The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned. tags: - Internal API - Recordings security: diff --git a/backend/openapi/paths/internal/rooms.yaml b/backend/openapi/paths/internal/rooms.yaml index 45acc75..0a614d5 100644 --- a/backend/openapi/paths/internal/rooms.yaml +++ b/backend/openapi/paths/internal/rooms.yaml @@ -106,9 +106,10 @@ get: operationId: getRoomRoleAndPermissions summary: Get room role and permissions - description: > + 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 diff --git a/backend/openapi/paths/recordings.yaml b/backend/openapi/paths/recordings.yaml index 1d56d68..19baef4 100644 --- a/backend/openapi/paths/recordings.yaml +++ b/backend/openapi/paths/recordings.yaml @@ -2,12 +2,12 @@ get: operationId: getRecordings summary: Get all recordings - description: > + description: | Retrieves a paginated list of all recordings available in the system. You can apply filters to narrow down the results based on specific criteria. > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method, - the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned. + > the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned. tags: - OpenVidu Meet - Recordings security: @@ -15,27 +15,7 @@ - accessTokenCookie: [] - recordingTokenCookie: [] parameters: - # - name: status - # in: query - # required: false - # description: | - # Filter recordings by their status. - - # Possible values: - # - `STARTING` - # - `ACTIVE` - # - `ENDING` - # - `COMPLETE` - # - `FAILED` - # - `ABORTED` - # - `LIMITED_REACHED` - - # You can provide multiple statuses as a comma-separated list (e.g., `status=ACTIVE,FAILED`). - # If not specified, recordings with any status will be returned. - - # > ⚠️ **Note:** Using this filter may impact performance for large datasets. - # schema: - # type: string + # - $ref: '../components/parameters/recording-status.yaml' - $ref: '../components/parameters/recording-fields.yaml' - $ref: '../components/parameters/room-id-query.yaml' - $ref: '../components/parameters/max-items.yaml' @@ -55,12 +35,12 @@ delete: operationId: bulkDeleteRecordings summary: Bulk delete recordings - description: > + description: | Deletes multiple recordings at once with the specified recording IDs. > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method, - all specified recordings must belong to the same room included in the token. - If a recording does not belong to that room, it will not be deleted. + > all specified recordings must belong to the same room included in the token. + > If a recording does not belong to that room, it will not be deleted. tags: - OpenVidu Meet - Recordings security: @@ -89,13 +69,13 @@ get: operationId: downloadRecordings summary: Download recordings - description: > + description: | Downloads multiple recordings as a ZIP file with the specified recording IDs. The ZIP file will contain all recordings in MP4 format. > **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method, - all specified recordings must belong to the same room included in the token. - If a recording does not belong to that room, it will not be included in the ZIP file. + > all specified recordings must belong to the same room included in the token. + > If a recording does not belong to that room, it will not be included in the ZIP file. tags: - OpenVidu Meet - Recordings security: @@ -145,6 +125,7 @@ - recordingTokenCookie: [] parameters: - $ref: '../components/parameters/recording-id.yaml' + - $ref: '../components/parameters/recording-secret.yaml' responses: '200': $ref: '../components/responses/success-get-recording.yaml' @@ -163,9 +144,11 @@ delete: operationId: deleteRecording summary: Delete a recording - description: > - Deletes a recording with the specified recording. - The recording will only be deleted if it exists and is not in progress (i.e., not in a state such as `ACTIVE`, `STARTING`, or `ENDING`). + description: | + Deletes a recording with the specified recording ID. + + > ⚠️ **Note:** The recording will only be deleted if it exists and is not in progress + > (i.e., not in a state such as `ACTIVE`, `STARTING`, or `ENDING`). tags: - OpenVidu Meet - Recordings security: @@ -193,9 +176,10 @@ get: operationId: getRecordingMedia summary: Get recording media - description: > + description: | Retrieves the media of a recording with the specified recording ID. The media is returned in a binary format suitable for video playback. + This endpoint supports range requests, allowing partial content retrieval for video playback without downloading the entire file. tags: @@ -210,7 +194,7 @@ - $ref: '../components/parameters/recording-range.yaml' responses: '200': - description: Successfully streaming the full recording + description: Successfully retrieved the full recording media headers: Accept-Ranges: $ref: '../components/headers/accept-ranges.yaml' @@ -224,7 +208,7 @@ type: string format: binary '206': - description: Partial content streaming based on byte range + description: Successfully retrieved a partial range of the recording media headers: Accept-Ranges: $ref: '../components/headers/accept-ranges.yaml' @@ -256,8 +240,8 @@ schema: $ref: '../components/schemas/error.yaml' example: - code: 416 - message: 'Requested range not satisfiable' + error: Recording Error + message: 'Recording "room-123--EG_XYZ--XX445" range not satisfiable. File size: 123456789' '422': $ref: '../components/responses/validation-error.yaml' '500': @@ -266,9 +250,10 @@ get: operationId: getRecordingUrl summary: Get recording URL - description: > + description: | Retrieves the URL of a recording with the specified recording ID. This URL is intended to be shared with people who do not have direct access to the recording. + It can be configured to be accessible by anyone (public access) or restricted to authenticated users only, depending on the `privateAccess` query parameter. tags: diff --git a/backend/openapi/paths/rooms.yaml b/backend/openapi/paths/rooms.yaml index 9c8a304..cc6faea 100644 --- a/backend/openapi/paths/rooms.yaml +++ b/backend/openapi/paths/rooms.yaml @@ -3,7 +3,7 @@ operationId: createRoom summary: Create a room description: > - Creates a new OpenVidu Meet room with the specified expiration date. + Creates a new OpenVidu Meet room. The room will be available for participants to join using the generated URLs. tags: - OpenVidu Meet - Room @@ -29,6 +29,7 @@ summary: Get all rooms description: > Retrieves a paginated list of all rooms available in the system. + You can apply filters to narrow down the results based on specific criteria. tags: - OpenVidu Meet - Room security: @@ -53,7 +54,7 @@ delete: operationId: bulkDeleteRooms summary: Bulk delete rooms - description: > + description: | Delete multiple OpenVidu Meet rooms at once with the specified room IDs. If a room has active participants, it will be marked for deletion @@ -120,7 +121,7 @@ delete: operationId: deleteRoom summary: Delete a room - description: > + description: | Deletes an OpenVidu Meet room with the specified room ID. If the room has active participants, it will be marked for deletion diff --git a/backend/openapi/webhooks/webhooks.yaml b/backend/openapi/webhooks/webhooks.yaml index 9c2e3d5..96323a3 100644 --- a/backend/openapi/webhooks/webhooks.yaml +++ b/backend/openapi/webhooks/webhooks.yaml @@ -1,7 +1,7 @@ recordingStarted: post: summary: Recording started - description: > + description: | This webhook is triggered when a recording starts. > The recording can be in the `STARTING` status for a few seconds before it becomes `ACTIVE`. @@ -31,7 +31,7 @@ recordingStarted: - properties: status: type: string - enum: [STARTING] + enum: [STARTING, ACTIVE] description: The status of the recording. example: STARTING responses: @@ -41,7 +41,7 @@ recordingStarted: recordingUpdated: post: summary: Recording updated - description: > + description: | This webhook is triggered when a recording update occurs. > This update can be due to a change in the recording status (e.g., from `STARTING` to `ACTIVE`). @@ -81,10 +81,11 @@ recordingUpdated: recordingEnded: post: summary: Recording ended - description: > + description: | This webhook is triggered when a recording ends. - > The recording can end due to various reasons, such as the user stopping the recording or the recording reaching its maximum duration. + > The recording can end due to various reasons, such as the user stopping the recording + > or the recording reaching its maximum duration. operationId: recordingEndedWebhook parameters: - $ref: ../components/parameters/x-timestamp.yaml @@ -112,7 +113,7 @@ recordingEnded: - properties: status: type: string - enum: [COMPLETE, FAILED, ABORTED, LIMITED_REACHED] + enum: [COMPLETE, FAILED, ABORTED, LIMIT_REACHED] description: The status of the recording. example: COMPLETE endDate: