From 2c992619dc77314c404591e6df60f1bded0fea46 Mon Sep 17 00:00:00 2001 From: Carlos Santos <4a.santos@gmail.com> Date: Thu, 3 Apr 2025 14:12:49 +0200 Subject: [PATCH] backend: refactor openapi doc for better maintainability --- backend/nodemon.json | 4 +- .../parameters/internal/participant-name.yaml | 6 + .../parameters/internal/secret.yaml | 6 + .../components/parameters/max-items.yaml | 8 + .../parameters/next-page-token.yaml | 6 + .../components/parameters/recording-id.yaml | 7 + .../parameters/recording-range.yaml | 8 + .../components/parameters/room-id.yaml | 7 + .../requestBodies/create-room-request.yaml | 6 + .../requestBodies/internal/login-user.yaml | 15 + .../internal/participant-token-request.yaml | 5 + .../start-recording-request.yaml | 13 + .../requestBodies/update-room-request.yaml | 33 + .../error-recording-already-started.yaml | 8 + .../error-recording-in-progress.yaml | 8 + .../responses/error-recording-not-found.yaml | 8 + .../responses/error-room-not-found.yaml | 8 + .../components/responses/forbidden-error.yaml | 7 + .../responses/internal-server-error.yaml | 7 + .../internal/error-invalid-credentials.yaml | 7 + .../internal/error-invalid-refresh-token.yaml | 7 + .../internal/success-refresh-token.yaml | 17 + .../internal/success-user-login.yaml | 24 + .../internal/success-user-logout.yaml | 18 + .../success-bulk-delete-recordings.yaml | 58 + .../responses/success-create-room.yaml | 5 + .../responses/success-get-recording.yaml | 27 + .../responses/success-get-recordings.yaml | 52 + .../responses/success-get-rooms.yaml | 19 + .../responses/success-start-recording.yaml | 11 + .../responses/success-stop-recording.yaml | 19 + .../responses/unauthorized-error.yaml | 7 + .../responses/validation-error.yaml | 5 + backend/openapi/components/schemas/error.yaml | 11 + .../schemas/internal/meet-token-options.yaml | 21 + .../components/schemas/meet-pagination.yaml | 10 + .../components/schemas/meet-recording.yaml | 54 + .../components/schemas/meet-room-options.yaml | 25 + .../schemas/meet-room-preferences.yaml | 45 + .../openapi/components/schemas/meet-room.yaml | 45 + .../components/schemas/meet-webhook.yaml | 39 + .../components/schemas/validation-error.yaml | 19 + backend/openapi/components/security.yaml | 18 + backend/openapi/info/info.yaml | 14 + backend/openapi/openvidu-meet-api.yaml | 1141 +---------------- .../openapi/openvidu-meet-internal-api.yaml | 700 +--------- backend/openapi/paths/internal/auth.yaml | 78 ++ .../openapi/paths/internal/participants.yaml | 125 ++ .../openapi/paths/internal/recordings.yaml | 78 ++ backend/openapi/paths/internal/rooms.yaml | 29 + backend/openapi/paths/recordings.yaml | 180 +++ backend/openapi/paths/rooms.yaml | 132 ++ backend/openapi/tags/tags.yaml | 12 + backend/openapi/webhooks/webhooks.yaml | 161 +++ backend/package.json | 4 +- 55 files changed, 1582 insertions(+), 1805 deletions(-) create mode 100644 backend/openapi/components/parameters/internal/participant-name.yaml create mode 100644 backend/openapi/components/parameters/internal/secret.yaml create mode 100644 backend/openapi/components/parameters/max-items.yaml create mode 100644 backend/openapi/components/parameters/next-page-token.yaml create mode 100644 backend/openapi/components/parameters/recording-id.yaml create mode 100644 backend/openapi/components/parameters/recording-range.yaml create mode 100644 backend/openapi/components/parameters/room-id.yaml create mode 100644 backend/openapi/components/requestBodies/create-room-request.yaml create mode 100644 backend/openapi/components/requestBodies/internal/login-user.yaml create mode 100644 backend/openapi/components/requestBodies/internal/participant-token-request.yaml create mode 100644 backend/openapi/components/requestBodies/start-recording-request.yaml create mode 100644 backend/openapi/components/requestBodies/update-room-request.yaml create mode 100644 backend/openapi/components/responses/error-recording-already-started.yaml create mode 100644 backend/openapi/components/responses/error-recording-in-progress.yaml create mode 100644 backend/openapi/components/responses/error-recording-not-found.yaml create mode 100644 backend/openapi/components/responses/error-room-not-found.yaml create mode 100644 backend/openapi/components/responses/forbidden-error.yaml create mode 100644 backend/openapi/components/responses/internal-server-error.yaml create mode 100644 backend/openapi/components/responses/internal/error-invalid-credentials.yaml create mode 100644 backend/openapi/components/responses/internal/error-invalid-refresh-token.yaml create mode 100644 backend/openapi/components/responses/internal/success-refresh-token.yaml create mode 100644 backend/openapi/components/responses/internal/success-user-login.yaml create mode 100644 backend/openapi/components/responses/internal/success-user-logout.yaml create mode 100644 backend/openapi/components/responses/success-bulk-delete-recordings.yaml create mode 100644 backend/openapi/components/responses/success-create-room.yaml create mode 100644 backend/openapi/components/responses/success-get-recording.yaml create mode 100644 backend/openapi/components/responses/success-get-recordings.yaml create mode 100644 backend/openapi/components/responses/success-get-rooms.yaml create mode 100644 backend/openapi/components/responses/success-start-recording.yaml create mode 100644 backend/openapi/components/responses/success-stop-recording.yaml create mode 100644 backend/openapi/components/responses/unauthorized-error.yaml create mode 100644 backend/openapi/components/responses/validation-error.yaml create mode 100644 backend/openapi/components/schemas/error.yaml create mode 100644 backend/openapi/components/schemas/internal/meet-token-options.yaml create mode 100644 backend/openapi/components/schemas/meet-pagination.yaml create mode 100644 backend/openapi/components/schemas/meet-recording.yaml create mode 100644 backend/openapi/components/schemas/meet-room-options.yaml create mode 100644 backend/openapi/components/schemas/meet-room-preferences.yaml create mode 100644 backend/openapi/components/schemas/meet-room.yaml create mode 100644 backend/openapi/components/schemas/meet-webhook.yaml create mode 100644 backend/openapi/components/schemas/validation-error.yaml create mode 100644 backend/openapi/components/security.yaml create mode 100644 backend/openapi/info/info.yaml create mode 100644 backend/openapi/paths/internal/auth.yaml create mode 100644 backend/openapi/paths/internal/participants.yaml create mode 100644 backend/openapi/paths/internal/recordings.yaml create mode 100644 backend/openapi/paths/internal/rooms.yaml create mode 100644 backend/openapi/paths/recordings.yaml create mode 100644 backend/openapi/paths/rooms.yaml create mode 100644 backend/openapi/tags/tags.yaml create mode 100644 backend/openapi/webhooks/webhooks.yaml diff --git a/backend/nodemon.json b/backend/nodemon.json index b2a1a6a..75d403f 100644 --- a/backend/nodemon.json +++ b/backend/nodemon.json @@ -2,8 +2,8 @@ "env": { "NODE_ENV": "development" }, - "watch": ["openapi/openvidu-meet-api.yaml", "openapi/openvidu-meet-internal-api.yaml", "src", "../typings/src"], - "ext": "js,json,ts", + "watch": ["openapi/**/*.yaml", "src", "../typings/src"], + "ext": "js,json,ts,yaml,yml", "ignore": ["node_modules", "dist", "src/typings", "public"], "exec": "node --experimental-specifier-resolution=node --loader ts-node/esm ./src/server.ts", "events": { diff --git a/backend/openapi/components/parameters/internal/participant-name.yaml b/backend/openapi/components/parameters/internal/participant-name.yaml new file mode 100644 index 0000000..3702f0b --- /dev/null +++ b/backend/openapi/components/parameters/internal/participant-name.yaml @@ -0,0 +1,6 @@ +name: participantName +in: path +required: true +description: The name of the participant to delete +schema: + type: string diff --git a/backend/openapi/components/parameters/internal/secret.yaml b/backend/openapi/components/parameters/internal/secret.yaml new file mode 100644 index 0000000..56615b2 --- /dev/null +++ b/backend/openapi/components/parameters/internal/secret.yaml @@ -0,0 +1,6 @@ +name: secret +in: query +required: true +description: The secret token from the room URL to check the participant's role +schema: + type: string diff --git a/backend/openapi/components/parameters/max-items.yaml b/backend/openapi/components/parameters/max-items.yaml new file mode 100644 index 0000000..a26946b --- /dev/null +++ b/backend/openapi/components/parameters/max-items.yaml @@ -0,0 +1,8 @@ +name: maxItems +in: query +required: false +description: The number of rooms per page (default is 10). Maximum is 100. +schema: + type: integer + default: 10 + maximum: 100 diff --git a/backend/openapi/components/parameters/next-page-token.yaml b/backend/openapi/components/parameters/next-page-token.yaml new file mode 100644 index 0000000..5c86f32 --- /dev/null +++ b/backend/openapi/components/parameters/next-page-token.yaml @@ -0,0 +1,6 @@ +name: nextPageToken +in: query +required: false +description: The token to retrieve the next page of rooms. +schema: + type: string diff --git a/backend/openapi/components/parameters/recording-id.yaml b/backend/openapi/components/parameters/recording-id.yaml new file mode 100644 index 0000000..c3b0dcb --- /dev/null +++ b/backend/openapi/components/parameters/recording-id.yaml @@ -0,0 +1,7 @@ +name: recordingId +in: path +required: true +description: The unique identifier of the recording to delete. +schema: + type: string + example: 'room-123--EG_XYZ--XX445' diff --git a/backend/openapi/components/parameters/recording-range.yaml b/backend/openapi/components/parameters/recording-range.yaml new file mode 100644 index 0000000..13b12b8 --- /dev/null +++ b/backend/openapi/components/parameters/recording-range.yaml @@ -0,0 +1,8 @@ +name: Range +in: header +required: false +description: > + Byte range for partial content retrieval. + Example: `bytes=0-1023` to request the first 1024 bytes of the file. +schema: + type: string diff --git a/backend/openapi/components/parameters/room-id.yaml b/backend/openapi/components/parameters/room-id.yaml new file mode 100644 index 0000000..0e02feb --- /dev/null +++ b/backend/openapi/components/parameters/room-id.yaml @@ -0,0 +1,7 @@ +name: roomId +in: path +required: true +description: The unique identifier of the room to retrieve +schema: + type: string + example: 'room-123' diff --git a/backend/openapi/components/requestBodies/create-room-request.yaml b/backend/openapi/components/requestBodies/create-room-request.yaml new file mode 100644 index 0000000..6ae8110 --- /dev/null +++ b/backend/openapi/components/requestBodies/create-room-request.yaml @@ -0,0 +1,6 @@ +description: Room creation details +required: true +content: + application/json: + schema: + $ref: '../schemas/meet-room-options.yaml' diff --git a/backend/openapi/components/requestBodies/internal/login-user.yaml b/backend/openapi/components/requestBodies/internal/login-user.yaml new file mode 100644 index 0000000..0809a77 --- /dev/null +++ b/backend/openapi/components/requestBodies/internal/login-user.yaml @@ -0,0 +1,15 @@ +description: User credentials +required: true +content: + application/json: + schema: + type: object + properties: + username: + type: string + example: 'admin' + description: The username of the user. + password: + type: string + example: 'password123' + description: The password of the user. diff --git a/backend/openapi/components/requestBodies/internal/participant-token-request.yaml b/backend/openapi/components/requestBodies/internal/participant-token-request.yaml new file mode 100644 index 0000000..3e28ed9 --- /dev/null +++ b/backend/openapi/components/requestBodies/internal/participant-token-request.yaml @@ -0,0 +1,5 @@ +description: Participant details +content: + application/json: + schema: + $ref: '../../schemas/internal/meet-token-options.yaml' diff --git a/backend/openapi/components/requestBodies/start-recording-request.yaml b/backend/openapi/components/requestBodies/start-recording-request.yaml new file mode 100644 index 0000000..7265847 --- /dev/null +++ b/backend/openapi/components/requestBodies/start-recording-request.yaml @@ -0,0 +1,13 @@ +description: Recording details +content: + application/json: + schema: + type: object + required: + - roomId + properties: + roomId: + type: string + example: 'room-123' + description: > + The unique identifier of the room to record. \ No newline at end of file diff --git a/backend/openapi/components/requestBodies/update-room-request.yaml b/backend/openapi/components/requestBodies/update-room-request.yaml new file mode 100644 index 0000000..d93380b --- /dev/null +++ b/backend/openapi/components/requestBodies/update-room-request.yaml @@ -0,0 +1,33 @@ +description: Room update details +content: + application/json: + schema: + $ref: '../schemas/meet-room-preferences.yaml#/MeetRoomPreferences' + examples: + default: + summary: Standard preferences + value: + chatPreferences: + enabled: true + recordingPreferences: + enabled: true + virtualBackgroundPreferences: + enabled: true + withoutRecording: + summary: Room with recording disabled + value: + chatPreferences: + enabled: true + recordingPreferences: + enabled: false + virtualBackgroundPreferences: + enabled: true + withoutChat: + summary: Room with chat disabled + value: + chatPreferences: + enabled: false + recordingPreferences: + enabled: true + virtualBackgroundPreferences: + enabled: true diff --git a/backend/openapi/components/responses/error-recording-already-started.yaml b/backend/openapi/components/responses/error-recording-already-started.yaml new file mode 100644 index 0000000..18ab0b4 --- /dev/null +++ b/backend/openapi/components/responses/error-recording-already-started.yaml @@ -0,0 +1,8 @@ +description: Conflict — The room is already being recorded +content: + application/json: + schema: + $ref: '../schemas/error.yaml' + example: + name: 'Recording Error' + message: 'The room "room-123" is already being recorded' diff --git a/backend/openapi/components/responses/error-recording-in-progress.yaml b/backend/openapi/components/responses/error-recording-in-progress.yaml new file mode 100644 index 0000000..979cd8a --- /dev/null +++ b/backend/openapi/components/responses/error-recording-in-progress.yaml @@ -0,0 +1,8 @@ +description: Conflict — The recording is in progress +content: + application/json: + schema: + $ref: '../schemas/error.yaml' + example: + name: 'Recording Error' + message: 'Recording "room-123--EG_XYZ--XX445" is in progress' diff --git a/backend/openapi/components/responses/error-recording-not-found.yaml b/backend/openapi/components/responses/error-recording-not-found.yaml new file mode 100644 index 0000000..59c5c67 --- /dev/null +++ b/backend/openapi/components/responses/error-recording-not-found.yaml @@ -0,0 +1,8 @@ +description: Recording not found +content: + application/json: + schema: + $ref: '../schemas/error.yaml' + example: + name: 'Recording Error' + message: 'Recording "room-123--EG_XYZ--XX445" not found' diff --git a/backend/openapi/components/responses/error-room-not-found.yaml b/backend/openapi/components/responses/error-room-not-found.yaml new file mode 100644 index 0000000..c8dd91d --- /dev/null +++ b/backend/openapi/components/responses/error-room-not-found.yaml @@ -0,0 +1,8 @@ +description: Room not found +content: + application/json: + schema: + $ref: '../schemas/error.yaml' + example: + code: 404 + message: 'Room not found' diff --git a/backend/openapi/components/responses/forbidden-error.yaml b/backend/openapi/components/responses/forbidden-error.yaml new file mode 100644 index 0000000..9b3a5a9 --- /dev/null +++ b/backend/openapi/components/responses/forbidden-error.yaml @@ -0,0 +1,7 @@ +description: Forbidden — Insufficient permissions +content: + application/json: + schema: + $ref: '../schemas/error.yaml' + example: + message: 'Insufficient permissions to access this resource' diff --git a/backend/openapi/components/responses/internal-server-error.yaml b/backend/openapi/components/responses/internal-server-error.yaml new file mode 100644 index 0000000..1ecc014 --- /dev/null +++ b/backend/openapi/components/responses/internal-server-error.yaml @@ -0,0 +1,7 @@ +description: Internal server error +content: + application/json: + schema: + $ref: '../schemas/error.yaml' + example: + message: 'Internal server error' diff --git a/backend/openapi/components/responses/internal/error-invalid-credentials.yaml b/backend/openapi/components/responses/internal/error-invalid-credentials.yaml new file mode 100644 index 0000000..72eace1 --- /dev/null +++ b/backend/openapi/components/responses/internal/error-invalid-credentials.yaml @@ -0,0 +1,7 @@ +description: Invalid credentials +content: + application/json: + schema: + $ref: ../../schemas/error.yaml + example: + message: 'Login failed. Invalid username or password' diff --git a/backend/openapi/components/responses/internal/error-invalid-refresh-token.yaml b/backend/openapi/components/responses/internal/error-invalid-refresh-token.yaml new file mode 100644 index 0000000..b96e791 --- /dev/null +++ b/backend/openapi/components/responses/internal/error-invalid-refresh-token.yaml @@ -0,0 +1,7 @@ +description: Bad Request — The refresh token is missing or invalid +content: + application/json: + schema: + $ref: ../../schemas/error.yaml + example: + message: 'No refresh token provided' diff --git a/backend/openapi/components/responses/internal/success-refresh-token.yaml b/backend/openapi/components/responses/internal/success-refresh-token.yaml new file mode 100644 index 0000000..57a8c5c --- /dev/null +++ b/backend/openapi/components/responses/internal/success-refresh-token.yaml @@ -0,0 +1,17 @@ +description: Successfully refreshed the access token +headers: + Set-Cookie: + description: > + The cookie containing the new access token. + This cookie is used to authenticate the user in subsequent requests. + schema: + type: string + example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' +content: + application/json: + schema: + type: object + properties: + message: + type: string + example: 'Token refreshed' diff --git a/backend/openapi/components/responses/internal/success-user-login.yaml b/backend/openapi/components/responses/internal/success-user-login.yaml new file mode 100644 index 0000000..b7767a5 --- /dev/null +++ b/backend/openapi/components/responses/internal/success-user-login.yaml @@ -0,0 +1,24 @@ +description: Successfully logged in +headers: + Set-Cookie: + description: > + The cookie containing the access token. + This cookie is used to authenticate the user in subsequent requests. + schema: + type: string + example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' + Set-Cookie-Refresh: + description: > + The cookie containing the refresh token. + 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' +content: + application/json: + schema: + type: object + properties: + message: + type: string + example: 'Login succeeded' diff --git a/backend/openapi/components/responses/internal/success-user-logout.yaml b/backend/openapi/components/responses/internal/success-user-logout.yaml new file mode 100644 index 0000000..c2964f3 --- /dev/null +++ b/backend/openapi/components/responses/internal/success-user-logout.yaml @@ -0,0 +1,18 @@ +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' diff --git a/backend/openapi/components/responses/success-bulk-delete-recordings.yaml b/backend/openapi/components/responses/success-bulk-delete-recordings.yaml new file mode 100644 index 0000000..c04ebb6 --- /dev/null +++ b/backend/openapi/components/responses/success-bulk-delete-recordings.yaml @@ -0,0 +1,58 @@ +description: Bulk deletion completed. Includes lists of successfully deleted IDs and errors. +content: + application/json: + schema: + type: object + properties: + deleted: + type: array + items: + type: string + description: List of successfully deleted recording IDs. + example: + - 'room-123--EG_XYZ--XX445' + - 'room-123--EG_XYZ--XX446' + notDeleted: + type: array + description: List of recordings that could not be deleted along with the corresponding error messages. + items: + type: object + properties: + recordingId: + type: string + description: The unique identifier of the recording that was not deleted. + example: 'room-123--EG_XYZ--XX447' + error: + type: string + description: A message explaining why the deletion failed. + example: 'Recording not found' + examples: + successful_deletion: + summary: All recordings were successfully deleted + value: + deleted: + - 'room-123--EG_XYZ--XX445' + - 'room-123--EG_XYZ--XX446' + notDeleted: [] + + partial_deletion_with_errors: + summary: Some recordings were deleted successfully, others failed + value: + deleted: + - 'room-123--EG_XYZ--XX445' + - 'room-123--EG_XYZ--XX446' + notDeleted: + - recordingId: 'room-123--EG_XYZ--XX447' + error: 'Recording not found' + - recordingId: 'room-123--EG_XYZ--XX448' + error: 'Access denied for deletion' + + 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_XYZ--XX446' + error: 'Recording not found' diff --git a/backend/openapi/components/responses/success-create-room.yaml b/backend/openapi/components/responses/success-create-room.yaml new file mode 100644 index 0000000..d72eba1 --- /dev/null +++ b/backend/openapi/components/responses/success-create-room.yaml @@ -0,0 +1,5 @@ +description: Success room response +content: + application/json: + schema: + $ref: '../schemas/meet-room.yaml' diff --git a/backend/openapi/components/responses/success-get-recording.yaml b/backend/openapi/components/responses/success-get-recording.yaml new file mode 100644 index 0000000..fa28bda --- /dev/null +++ b/backend/openapi/components/responses/success-get-recording.yaml @@ -0,0 +1,27 @@ +description: Successfully retrieved the recording. +content: + application/json: + schema: + $ref: '../schemas/meet-recording.yaml' + examples: + completed_recording: + summary: Completed recording + value: + recordingId: 'room-123--EG_XYZ--XX445' + roomId: 'room-123' + status: 'COMPLETE' + filename: 'room-123--XX445.mp4' + startDate: 1600000000000 + endDate: 1600000003600 + duration: 3.6 + size: 1443846 + details: 'End reason: StopEgress API' + + active_recording: + summary: Recording in progress + value: + recordingId: 'room-456--EG_ABC--QR789' + roomId: 'room-456' + status: 'ACTIVE' + filename: 'room-456--QR789.mp4' + startDate: 1682500000000 diff --git a/backend/openapi/components/responses/success-get-recordings.yaml b/backend/openapi/components/responses/success-get-recordings.yaml new file mode 100644 index 0000000..05352b3 --- /dev/null +++ b/backend/openapi/components/responses/success-get-recordings.yaml @@ -0,0 +1,52 @@ +description: Successfully retrieved the recording list +content: + application/json: + schema: + type: object + properties: + recordings: + type: array + items: + $ref: '../schemas/meet-recording.yaml' + pagination: + $ref: '../schemas/meet-pagination.yaml' + examples: + successful_recording_retrieval: + summary: Successfully retrieved a list of recordings + value: + recordings: + - recordingId: 'room-123--EG_XYZ--XX445' + roomId: 'room-123' + status: 'ACTIVE' + filename: 'room-123--XX445.mp4' + startDate: 1620000000000 + endDate: 1620000003600 + duration: 3.6 + size: 1024 + details: 'Stopped using API' + pagination: + isTruncated: false + + paginated_recording_list: + summary: A paginated response indicating more recordings are available + value: + recordings: + - recordingId: 'room-456--EG_XYZ--XX678' + roomId: 'room-456' + status: 'COMPLETE' + filename: 'room-456--XX678.mp4' + startDate: 1625000000000 + endDate: 1625000007200 + duration: 7.2 + size: 2048 + details: 'Recording completed successfully' + pagination: + isTruncated: true + nextPageToken: 'NEXT_PAGE_ABC123' + + no_recordings_found: + summary: No recordings found for the given query + value: + recordings: [] + pagination: + isTruncated: false diff --git a/backend/openapi/components/responses/success-get-rooms.yaml b/backend/openapi/components/responses/success-get-rooms.yaml new file mode 100644 index 0000000..e694da5 --- /dev/null +++ b/backend/openapi/components/responses/success-get-rooms.yaml @@ -0,0 +1,19 @@ +description: Successfully retrieved the list of OpenVidu Meet rooms +content: + application/json: + schema: + type: object + properties: + rooms: + type: array + items: + $ref: '../schemas/meet-room.yaml' + pagination: + type: object + properties: + isTruncated: + type: boolean + description: Indicates if there are more rooms to retrieve. + nextPageToken: + type: string + description: The token to retrieve the next page of rooms. diff --git a/backend/openapi/components/responses/success-start-recording.yaml b/backend/openapi/components/responses/success-start-recording.yaml new file mode 100644 index 0000000..b5410ff --- /dev/null +++ b/backend/openapi/components/responses/success-start-recording.yaml @@ -0,0 +1,11 @@ +description: Successfully created the OpenVidu Meet recording +content: + application/json: + schema: + $ref: '../schemas/meet-recording.yaml' + example: + recordingId: 'room-123--EG_XYZ--XX445' + roomId: 'room-123' + status: 'STARTING' + filename: 'room-123--EG_XYZ--XX445' + startDate: 1600000000000 diff --git a/backend/openapi/components/responses/success-stop-recording.yaml b/backend/openapi/components/responses/success-stop-recording.yaml new file mode 100644 index 0000000..a059c13 --- /dev/null +++ b/backend/openapi/components/responses/success-stop-recording.yaml @@ -0,0 +1,19 @@ +description: Accepted — The stop request has been accepted. The endpoint to retrieve the recording is provided in the Location header. +headers: + Location: + 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' +content: + application/json: + schema: + $ref: '../schemas/meet-recording.yaml' + example: + recordingId: 'room-123--EG_XYZ--XX445' + roomId: 'room-123' + status: 'ENDING' + filename: 'room-123--EG_XYZ--XX445' + startDate: 1600000000000 + duration: 3.6 + details: 'End reason: StopEgress API' diff --git a/backend/openapi/components/responses/unauthorized-error.yaml b/backend/openapi/components/responses/unauthorized-error.yaml new file mode 100644 index 0000000..fa6da95 --- /dev/null +++ b/backend/openapi/components/responses/unauthorized-error.yaml @@ -0,0 +1,7 @@ +description: Unauthorized — Invalid API key or access token +content: + application/json: + schema: + $ref: '../schemas/error.yaml' + example: + message: 'Unauthorized' diff --git a/backend/openapi/components/responses/validation-error.yaml b/backend/openapi/components/responses/validation-error.yaml new file mode 100644 index 0000000..f8a48e7 --- /dev/null +++ b/backend/openapi/components/responses/validation-error.yaml @@ -0,0 +1,5 @@ +description: Unprocessable Entity — Invalid request body +content: + application/json: + schema: + $ref: '../schemas/validation-error.yaml' diff --git a/backend/openapi/components/schemas/error.yaml b/backend/openapi/components/schemas/error.yaml new file mode 100644 index 0000000..681fe78 --- /dev/null +++ b/backend/openapi/components/schemas/error.yaml @@ -0,0 +1,11 @@ +type: object +required: + - message +properties: + name: + type: string + message: + type: string + code: + type: integer +description: HTTP status code associated with the error diff --git a/backend/openapi/components/schemas/internal/meet-token-options.yaml b/backend/openapi/components/schemas/internal/meet-token-options.yaml new file mode 100644 index 0000000..683bae4 --- /dev/null +++ b/backend/openapi/components/schemas/internal/meet-token-options.yaml @@ -0,0 +1,21 @@ +type: object +required: + - roomId + - participantName + - secret +properties: + roomId: + type: string + example: 'room-123' + description: > + The ID of the room where the participant will join. + participantName: + type: string + example: 'Alice' + description: > + The name of the participant. + secret: + type: string + example: 'abc123456' + description: > + The secret token from the room Url diff --git a/backend/openapi/components/schemas/meet-pagination.yaml b/backend/openapi/components/schemas/meet-pagination.yaml new file mode 100644 index 0000000..8c7c1f8 --- /dev/null +++ b/backend/openapi/components/schemas/meet-pagination.yaml @@ -0,0 +1,10 @@ +type: object +properties: + isTruncated: + type: boolean + description: > + Indicates if there are more recordings to retrieve. + If true, use the `nextPageToken` to fetch the next set of recordings. + nextPageToken: + type: [string, 'null'] + description: The token to retrieve the next page of recordings. diff --git a/backend/openapi/components/schemas/meet-recording.yaml b/backend/openapi/components/schemas/meet-recording.yaml new file mode 100644 index 0000000..0a9f957 --- /dev/null +++ b/backend/openapi/components/schemas/meet-recording.yaml @@ -0,0 +1,54 @@ +type: object +properties: + recordingId: + type: string + example: 'room-123--EG_XYZ--XX445' + description: The unique identifier of the recording. + roomId: + type: string + example: 'room-123' + description: The ID of the room where the recording was made. + # outputMode: + # type: string + # example: 'COMPOSED' + # description: > + # The output mode of the recording. Possible value: "COMPOSED". + status: + type: string + enum: ['STARTING', 'ACTIVE', 'ENDING', 'COMPLETE', 'FAILED', 'ABORTED', 'LIMITED_REACHED'] + example: 'ACTIVE' + description: > + The status of the recording. + filename: + type: string + example: 'room-123--XX445.mp4' + description: > + The URL for the publisher to join the room. The publisher has permissions to publish audio and + video streams to the room. + startDate: + type: [number, 'null'] + example: 1620000000000 + description: The date when the recording started (milliseconds since the Unix epoch). + endDate: + type: [number, 'null'] + example: 1620000003600 + description: The date when the recording was stopped (milliseconds since the Unix epoch). + duration: + type: [number, 'null'] + example: 3.6 + description: The duration of the recording in seconds. + size: + type: [number, 'null'] + example: 1024 + description: The size of the recording file in bytes. + errorCode: + type: [number, 'null'] + example: 100 + description: The error code of the recording. + error: + type: [string, 'null'] + description: The error message of the recording. + details: + type: [string, 'null'] + example: 'Stopped using API' + description: Additional details about the recording. diff --git a/backend/openapi/components/schemas/meet-room-options.yaml b/backend/openapi/components/schemas/meet-room-options.yaml new file mode 100644 index 0000000..5f2bde8 --- /dev/null +++ b/backend/openapi/components/schemas/meet-room-options.yaml @@ -0,0 +1,25 @@ +type: object +required: + - expirationDate +properties: + expirationDate: + type: number + example: 1620000000000 + description: > + The expiration date of the room in milliseconds since the Unix epoch. + After this date, the room will be closed and no new participants will be allowed to join. + roomIdPrefix: + type: string + example: 'room' + description: > + A prefix to be used for the room ID. The room ID will be generated by concatenating this prefix with a unique identifier. + # maxParticipants: + # type: integer + # example: 10 + # description: > + # The maximum number of participants allowed in the room. If the number of participants exceeds + # this limit, new participants will not be allowed to join. + preferences: + $ref: './meet-room-preferences.yaml#/MeetRoomPreferences' + description: > + The preferences for the room. These preferences wil diff --git a/backend/openapi/components/schemas/meet-room-preferences.yaml b/backend/openapi/components/schemas/meet-room-preferences.yaml new file mode 100644 index 0000000..d8f73c2 --- /dev/null +++ b/backend/openapi/components/schemas/meet-room-preferences.yaml @@ -0,0 +1,45 @@ +MeetRoomPreferences: + type: object + properties: + chatPreferences: + $ref: '#/MeetChatPreferences' + description: > + Preferences for the chat feature in the room. + + recordingPreferences: + $ref: '#/MeetRecordingPreferences' + description: > + Preferences for recording the room. + + virtualBackgroundPreferences: + $ref: '#/MeetVirtualBackgroundPreferences' + description: > + Preferences for virtual background in the room. + +MeetChatPreferences: + type: object + properties: + enabled: + type: boolean + default: true + example: true + description: > + If true, the room will be allowed to send and receive chat messages. +MeetRecordingPreferences: + type: object + properties: + enabled: + type: boolean + default: true + example: true + description: > + If true, the room will be allowed to record the video of the participants. +MeetVirtualBackgroundPreferences: + type: object + properties: + enabled: + type: boolean + default: true + example: true + description: > + If true, the room will be allowed to use virtual background. diff --git a/backend/openapi/components/schemas/meet-room.yaml b/backend/openapi/components/schemas/meet-room.yaml new file mode 100644 index 0000000..a546483 --- /dev/null +++ b/backend/openapi/components/schemas/meet-room.yaml @@ -0,0 +1,45 @@ +type: object +properties: + roomId: + type: string + example: 'room-123' + description: > + The unique identifier of the room. This ID is generated when the room is created. + roomIdPrefix: + type: string + example: 'room' + description: > + The prefix used for the room ID. This prefix is used to generate the room ID. + creationDate: + type: number + example: 1620000000000 + description: > + The creation date of the room in milliseconds since the Unix epoch. + expirationDate: + type: number + example: 1620000800000 + description: > + The expiration date of the room in milliseconds since the Unix epoch. + After this date, the room will be closed and no new participants will be allowed to join. + preferences: + $ref: meet-room-preferences.yaml#/MeetRoomPreferences + description: > + The preferences for the room. + # maxParticipants: + # type: integer + # example: 10 + # description: > + # The maximum number of participants allowed in the room. If the number of participants exceeds + # this limit, new participants will not be allowed to join. + moderatorURL: + type: string + example: 'http://localhost:6080/room/room-123/?secret=tok_123456' + description: > + The URL for the moderator to join the room. The moderator has special permissions to manage the + room and participants. + publisherURL: + type: string + example: 'http://localhost:6080/room/room-123/?secret=tok_123456' + description: > + The URL for the publisher to join the room. The publisher has permissions to publish audio and + video streams to the room. diff --git a/backend/openapi/components/schemas/meet-webhook.yaml b/backend/openapi/components/schemas/meet-webhook.yaml new file mode 100644 index 0000000..a9aafee --- /dev/null +++ b/backend/openapi/components/schemas/meet-webhook.yaml @@ -0,0 +1,39 @@ +MeetWebhookEvent: + type: object + properties: + creationDate: + type: number + description: 'The timestamp when the webhook event was created.' + event: + $ref: '#/MeetWebhookEventType' + description: 'The type of event.' + data: + oneOf: + - allOf: + - title: Recording Event Data + - description: 'Data for recording-related events (started, updated, ended)' + - $ref: './meet-recording.yaml' + # - allOf: + # - title: Room Event Data + # - description: 'Data for room-related events (created, updated, deleted)' + # - $ref: './meet-room.yaml' + discriminator: + propertyName: eventType + mapping: + recordingStarted: './meet-recording.yaml' + recordingUpdated: './meet-recording.yaml' + recordingEnded: './meet-recording.yaml' + # roomCreated: './meet-room.yaml' + # roomUpdated: './meet-room.yaml' + # roomDeleted: './meet-room.yaml' + description: 'The event payload data, determined by the event type.' + +MeetWebhookEventType: + type: string + enum: + - recordingStarted + - recordingUpdated + - recordingEnded + # - roomCreated + # - roomUpdated + # - roomDeleted diff --git a/backend/openapi/components/schemas/validation-error.yaml b/backend/openapi/components/schemas/validation-error.yaml new file mode 100644 index 0000000..8956176 --- /dev/null +++ b/backend/openapi/components/schemas/validation-error.yaml @@ -0,0 +1,19 @@ +type: object +properties: + error: + type: string + example: 'Unprocessable Entity' + message: + type: string + example: 'Invalid request body' + details: + type: array + items: + type: object + properties: + field: + type: string + example: 'expirationDate' + message: + type: string + example: 'Expected number, received string' diff --git a/backend/openapi/components/security.yaml b/backend/openapi/components/security.yaml new file mode 100644 index 0000000..55710c0 --- /dev/null +++ b/backend/openapi/components/security.yaml @@ -0,0 +1,18 @@ +apiKeyInHeader: + type: apiKey + name: X-API-KEY + in: header + description: > + The API key to authenticate the request. This key is required to access the OpenVidu Meet API. +accessTokenCookie: + type: apiKey + name: OvMeetAccessToken + in: cookie + description: > + The JWT token to authenticate the request in case of consuming the API from the OpenVidu Meet frontend. +participantTokenCookie: + type: apiKey + name: OvMeetParticipantToken + in: cookie + description: > + The JWT token to authenticate the participant when entering the room. diff --git a/backend/openapi/info/info.yaml b/backend/openapi/info/info.yaml new file mode 100644 index 0000000..3c3d67e --- /dev/null +++ b/backend/openapi/info/info.yaml @@ -0,0 +1,14 @@ +title: OpenVidu Meet REST API +description: > + The OpenVidu Meet REST API provides a comprehensive set of endpoints for integrating real-time video + conferencing capabilities into your applications. +contact: + name: OpenVidu + email: commercial@openvidu.io + url: https://openvidu.io/support/ +license: + name: Apache License 2.0 + identifier: Apache-2.0 + url: https://www.apache.org/licenses/LICENSE-2.0 +version: v1 +termsOfService: https://openvidu.io/conditions/terms-of-service/ diff --git a/backend/openapi/openvidu-meet-api.yaml b/backend/openapi/openvidu-meet-api.yaml index dd8e1e1..f2820f1 100644 --- a/backend/openapi/openvidu-meet-api.yaml +++ b/backend/openapi/openvidu-meet-api.yaml @@ -1,1142 +1,37 @@ openapi: 3.1.0 info: - title: OpenVidu Meet REST API - description: > - The OpenVidu Meet REST API provides a comprehensive set of endpoints for integrating real-time video - conferencing capabilities into your applications. - contact: - name: OpenVidu - email: commercial@openvidu.io - url: https://openvidu.io/support/ - license: - name: Apache License 2.0 - identifier: Apache-2.0 - url: https://www.apache.org/licenses/LICENSE-2.0 - version: v1 - termsOfService: https://openvidu.io/conditions/terms-of-service/ - + $ref: './info/info.yaml' servers: - url: /meet/api/v1 description: OpenVidu Meet API - tags: - - name: OpenVidu Meet - Room - description: Operations related to managing OpenVidu Meet rooms - - name: OpenVidu Meet - Recordings - description: Operations related to managing OpenVidu Meet recordings - + $ref: './tags/tags.yaml' +webhooks: + $ref: './webhooks/webhooks.yaml' paths: /rooms: - post: - operationId: createRoom - summary: Create a room - description: > - Creates a new OpenVidu Meet room with the specified expiration date. - The room will be available for participants to join using the generated URLs. - tags: - - OpenVidu Meet - Room - security: - - apiKeyInHeader: [] - - accessTokenCookie: [] - requestBody: - description: Room creation details - content: - application/json: - schema: - $ref: '#/components/schemas/MeetRoomOptions' - examples: - default: - value: - expirationDate: 1620000000000 - roomIdPrefix: 'room' - # maxParticipants: 10 - preferences: - chatPreferences: - enabled: true - recordingPreferences: - enabled: true - virtualBackgroundPreferences: - enabled: true - responses: - '200': - description: Successfully created the OpenVidu Meet room - content: - application/json: - schema: - $ref: '#/components/schemas/MeetRoom' - '401': - description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '422': - description: Unprocessable Entity — The request body is invalid - content: - application/json: - schema: - type: object - properties: - error: - type: string - example: 'Unprocessable Entity' - message: - type: string - example: 'Invalid request body' - details: - type: array - items: - type: object - properties: - field: - type: string - example: 'expirationDate' - message: - type: string - example: 'Expected number, received string' - example: - error: 'Unprocessable Entity' - message: 'Invalid request body' - details: - - field: 'expirationDate' - message: 'Expected number, received string' - - field: 'roomIdPrefix' - message: 'Expected string, received number' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Internal server error' - get: - operationId: getRooms - summary: Get all rooms - description: > - Retrieves a paginated list of all rooms available in the system. - tags: - - OpenVidu Meet - Room - security: - - apiKeyInHeader: [] - - accessTokenCookie: [] - parameters: - - name: maxItems - in: query - required: false - description: The number of rooms per page (default is 10). Maximum is 100. - schema: - type: integer - default: 10 - - name: nextPageToken - in: query - required: false - description: The token to retrieve the next page of rooms. - schema: - type: string - responses: - '200': - description: Successfully retrieved the list of OpenVidu Meet rooms - content: - application/json: - schema: - type: object - properties: - rooms: - type: array - items: - $ref: '#/components/schemas/MeetRoom' - pagination: - type: object - properties: - isTruncated: - type: boolean - description: Indicates if there are more rooms to retrieve. - nextPageToken: - type: string - description: The token to retrieve the next page of rooms. - - '401': - description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 500 - message: 'Internal server error' + $ref: './paths/rooms.yaml#/~1rooms' /rooms/{roomId}: - get: - operationId: getRoom - summary: Get a room - description: > - Retrieves the details of an OpenVidu Meet room with the specified room ID. - tags: - - OpenVidu Meet - Room - security: - - apiKeyInHeader: [] - - accessTokenCookie: [] - - participantTokenCookie: [] - parameters: - - name: roomId - in: path - required: true - description: The unique identifier of the room to retrieve - schema: - type: string - example: 'room-123' - responses: - '200': - description: Successfully retrieved the room - content: - application/json: - schema: - $ref: '#/components/schemas/MeetRoom' - '401': - description: Unauthorized — The API key is missing or invalid, or the access/participant token is missing or invalid when using cookie-based authentication - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The participant authenticated with the access token is not moderator of the room - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Room not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 404 - message: 'Room not found' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 500 - message: 'Internal server error' - put: - operationId: updateRoom - summary: Update a room - description: > - Updates the preferences of an OpenVidu Meet room with the specified room ID. - tags: - - OpenVidu Meet - Room - security: - - apiKeyInHeader: [] - - accessTokenCookie: [] - parameters: - - name: roomId - in: path - required: true - description: The unique identifier of the room to update - schema: - type: string - example: 'room-123' - requestBody: - description: Room update details - content: - application/json: - schema: - $ref: '#/components/schemas/MeetRoomPreferences' - examples: - default: - value: - preferences: - chatPreferences: - enabled: true - recordingPreferences: - enabled: true - virtualBackgroundPreferences: - enabled: true - responses: - '200': - description: Successfully updated the OpenVidu Meet room - content: - application/json: - schema: - $ref: '#/components/schemas/MeetRoom' - '401': - description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Room not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 404 - message: 'Room not found' - '422': - description: Unprocessable Entity — The request body is invalid - content: - application/json: - schema: - type: object - properties: - error: - type: string - example: 'Unprocessable Entity' - message: - type: string - example: 'Invalid request body' - details: - type: array - items: - type: object - properties: - field: - type: string - example: 'recordingPreferences' - message: - type: string - example: 'Expected boolean, received string' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 500 - message: 'Internal server error' - delete: - operationId: deleteRoom - summary: Delete a room - description: > - Deletes an OpenVidu Meet room with the specified room ID. - The room with participants will be closed and all participants will be disconnected. - The room will be deleted from the system and will no longer be available. - tags: - - OpenVidu Meet - Room - security: - - apiKeyInHeader: [] - - accessTokenCookie: [] - parameters: - - name: roomId - in: path - required: true - description: The unique identifier of the room to delete - schema: - type: string - example: 'room-123' - responses: - '204': - description: Successfully deleted the OpenVidu Meet room - '401': - description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Room not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 404 - message: 'Room not found' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 500 - message: 'Internal server error' + $ref: './paths/rooms.yaml#/~1rooms~1{roomId}' /recordings: - post: - operationId: createRecording - summary: Start a recording - description: > - Start a new recording for an OpenVidu Meet room with the specified room ID. - tags: - - OpenVidu Meet - Recordings - security: - - participantTokenCookie: [] - requestBody: - description: Recording details - content: - application/json: - schema: - type: object - required: - - roomId - properties: - roomId: - type: string - example: 'room-123' - description: > - The unique identifier of the room to record. - responses: - '200': - description: Successfully created the OpenVidu Meet recording - content: - application/json: - schema: - $ref: '#/components/schemas/MeetRecordingStart' - '401': - description: Unauthorized — The participant access token is missing or invalid - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — Recording is not enabled for the room or the participant authenticated with the access token has not enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Room not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Room Error' - message: 'The room "room-123" does not exist' - '409': - description: Conflict — The room is already being recorded - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Recording Error' - message: 'The room "room-123" is already being recorded' - '422': - description: Unprocessable Entity — The request body is invalid - content: - application/json: - schema: - type: object - properties: - error: - type: string - example: 'Unprocessable Entity' - message: - type: string - example: 'Invalid request body' - details: - type: array - items: - type: object - properties: - field: - type: string - example: 'roomId' - message: - type: string - example: 'roomId not found' - example: - error: 'Unprocessable Entity' - message: 'Invalid request body' - details: - - field: 'roomId' - example: 'roomId not found' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Unexpected Error' - message: 'Something went wrong' - get: - operationId: getRecordings - summary: Get all recordings - 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. - tags: - - OpenVidu Meet - Recordings - security: - - apiKeyInHeader: [] - - accessTokenCookie: [] - 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 - - name: roomId - in: query - required: false - description: | - The unique identifier of the room for which you want to retrieve recordings. - If not provided, recordings from all rooms will be returned. - schema: - type: string - - name: maxItems - in: query - required: false - description: The number of recordings per page (default is 10). Maximum is 100. - schema: - type: integer - default: 10 - - name: nextPageToken - in: query - required: false - description: The token to retrieve the next page of recordings. - schema: - type: string - responses: - '200': - description: Successfully retrieved the recording list - content: - application/json: - schema: - type: object - properties: - recordings: - type: array - items: - $ref: '#/components/schemas/MeetRecording' - pagination: - type: object - properties: - isTruncated: - type: boolean - description: Indicates if there are more recordings to retrieve. - nextPageToken: - type: string - description: The token to retrieve the next page of recordings. - - '401': - description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 500 - message: 'Internal server error' - delete: - operationId: bulkDeleteRecordings - summary: Bulk delete recordings - description: > - Deletes multiple recordings at once with the specified recording IDs. - tags: - - OpenVidu Meet - Recordings - security: - - apiKeyInHeader: [] - - accessTokenCookie: [] - parameters: - - name: recordingIds - in: query - required: true - description: | - The unique IDs of the recordings to delete. - You can provide multiple recording IDs as a comma-separated list (e.g., `recordingIds=room-123--EG_XYZ--XX445,room-123--EG_XYZ--XX446`). - schema: - type: string - responses: - '200': - description: Bulk deletion completed. Includes lists of successfully deleted IDs and errors. - content: - application/json: - schema: - type: object - properties: - deleted: - type: array - items: - type: string - description: List of successfully deleted recording IDs. - example: - - 'room-123--EG_XYZ--XX445' - - 'room-123--EG_XYZ--XX446' - notDeleted: - type: array - description: List of recordings that could not be deleted along with the corresponding error messages. - items: - type: object - properties: - recordingId: - type: string - description: The unique identifier of the recording that was not deleted. - example: 'room-123--EG_XYZ--XX447' - error: - type: string - description: A message explaining why the deletion failed. - example: 'Recording not found' - '401': - description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '422': - description: Unprocessable Entity — The request body is invalid - content: - application/json: - schema: - type: object - properties: - error: - type: string - example: 'Unprocessable Entity' - message: - type: string - example: 'Invalid request body' - details: - type: array - items: - type: object - properties: - field: - type: string - example: 'recordingIds' - message: - type: string - example: 'recordingIds not found' - example: - error: 'Unprocessable Entity' - message: 'Invalid request body' - details: - - field: 'recordingIds' - example: 'recordingIds not found' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Unexpected Error' - message: 'Something went wrong' + $ref: './paths/recordings.yaml#/~1recordings' /recordings/{recordingId}: - put: - operationId: stopRecording - summary: Stop a recording - description: > - Stops a recording with the specified recording ID. - The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned. - tags: - - OpenVidu Meet - Recordings - security: - - participantTokenCookie: [] - parameters: - - name: recordingId - in: path - required: true - description: The unique identifier of the recording to stop. - schema: - type: string - example: 'room-123--EG_XYZ--XX445' - responses: - '200': - description: Accepted — The stop request has been accepted. The endpoint to retrieve the recording is provided in the Location header. - headers: - Location: - 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' - content: - application/json: - schema: - $ref: '#/components/schemas/MeetRecording' - '401': - description: Unauthorized — The participant access token is missing or invalid - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — Recording is not enabled for the room or the participant authenticated with the access token has not enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Recording not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Recording Error' - message: 'Recording "room-123--EG_XYZ--XX445" not found' - '409': - description: Conflict — The recording is already stopped. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Recording Error' - message: 'Recording "room-123--EG_XYZ--XX445" is already stopped' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Unexpected Error' - message: 'Something went wrong' - get: - operationId: getRecording - summary: Get a recording - description: > - Retrieves the details of a recording with the specified recording ID. - tags: - - OpenVidu Meet - Recordings - security: - - apiKeyInHeader: [] - - accessTokenCookie: [] - parameters: - - name: recordingId - in: path - required: true - description: The unique identifier of the recording to retrieve - schema: - type: string - example: 'room-123--EG_XYZ--XX445' - responses: - '200': - description: Successfully retrieved the recording. - content: - application/json: - schema: - $ref: '#/components/schemas/MeetRecording' - - '401': - description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Recording not found — The recording with the specified ID was not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Recording Error' - message: 'Recording "room-123--EG_XYZ--XX445" not found' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Unexpected Error' - message: 'Something went wrong' - 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`). - tags: - - OpenVidu Meet - Recordings - security: - - apiKeyInHeader: [] - - accessTokenCookie: [] - parameters: - - name: recordingId - in: path - required: true - description: The unique identifier of the recording to delete. - schema: - type: string - example: 'room-123--EG_XYZ--XX445' - responses: - '204': - description: Recording successfully deleted. No content is returned. - '401': - description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Recording not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Recording Error' - message: 'Recording "room-123--EG_XYZ--XX445" not found' - '409': - description: Conflict — The recording is in progress - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Recording Error' - message: 'Recording "room-123--EG_XYZ--XX445" is in progress' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Unexpected Error' - message: 'Something went wrong' + $ref: './paths/recordings.yaml#/~1recordings~1{recordingId}' components: securitySchemes: - apiKeyInHeader: - type: apiKey - name: X-API-KEY - in: header - description: > - The API key to authenticate the request. This key is required to access the OpenVidu Meet API. - accessTokenCookie: - type: apiKey - name: OvMeetAccessToken - in: cookie - description: > - The JWT token to authenticate the request in case of consuming the API from the OpenVidu Meet frontend. - participantTokenCookie: - type: apiKey - name: OvMeetParticipantToken - in: cookie - description: > - The JWT token to authenticate the participant when entering the room. + $ref: './components/security.yaml' + # responses: + # $ref: './components/responses.yaml' schemas: MeetRoom: - type: object - properties: - roomId: - type: string - example: 'room-123' - description: > - The unique identifier of the room. This ID is generated when the room is created. - roomIdPrefix: - type: string - example: 'room' - description: > - The prefix used for the room ID. This prefix is used to generate the room ID. - creationDate: - type: number - example: 1620000000000 - description: > - The creation date of the room in milliseconds since the Unix epoch. - expirationDate: - type: number - example: 1620000000000 - description: > - The expiration date of the room in milliseconds since the Unix epoch. - After this date, the room will be closed and no new participants will be allowed to join. - preferences: - $ref: '#/components/schemas/MeetRoomPreferences' - description: > - The preferences for the room. - # maxParticipants: - # type: integer - # example: 10 - # description: > - # The maximum number of participants allowed in the room. If the number of participants exceeds - # this limit, new participants will not be allowed to join. - moderatorURL: - type: string - example: 'http://localhost:6080/room/room-123/?secret=tok_123456' - description: > - The URL for the moderator to join the room. The moderator has special permissions to manage the - room and participants. - publisherURL: - type: string - example: 'http://localhost:6080/room/room-123/?secret=tok_123456' - description: > - The URL for the publisher to join the room. The publisher has permissions to publish audio and - video streams to the room. - + $ref: components/schemas/meet-room.yaml MeetRoomOptions: - type: object - required: - - expirationDate - properties: - expirationDate: - type: number - example: 1620000000000 - description: > - The expiration date of the room in milliseconds since the Unix epoch. - After this date, the room will be closed and no new participants will be allowed to join. - roomIdPrefix: - type: string - example: 'room' - description: > - A prefix to be used for the room ID. The room ID will be generated by concatenating this prefix with a unique identifier. - # maxParticipants: - # type: integer - # example: 10 - # description: > - # The maximum number of participants allowed in the room. If the number of participants exceeds - # this limit, new participants will not be allowed to join. - preferences: - $ref: '#/components/schemas/MeetRoomPreferences' - description: > - The preferences for the room. These preferences will be applied to the room when it is created. + $ref: components/schemas/meet-room-options.yaml MeetRoomPreferences: - type: object - properties: - chatPreferences: - $ref: '#/components/schemas/MeetChatPreferences' - description: > - Preferences for the chat feature in the room. - - recordingPreferences: - $ref: '#/components/schemas/MeetRecordingPreferences' - description: > - Preferences for recording the room. - - virtualBackgroundPreferences: - $ref: '#/components/schemas/MeetVirtualBackgroundPreferences' - description: > - Preferences for virtual background in the room. - MeetChatPreferences: - type: object - properties: - enabled: - type: boolean - default: true - example: true - description: > - If true, the room will be allowed to send and receive chat messages. - MeetRecordingPreferences: - type: object - properties: - enabled: - type: boolean - default: true - example: true - description: > - If true, the room will be allowed to record the video of the participants. - MeetVirtualBackgroundPreferences: - type: object - properties: - enabled: - type: boolean - default: true - example: true - description: > - If true, the room will be allowed to use virtual background. - MeetRecordingBase: - type: object - properties: - recordingId: - type: string - example: 'room-123--EG_XYZ--XX445' - description: The unique identifier of the recording. - roomId: - type: string - example: 'room-123' - description: The ID of the room where the recording was made. - # outputMode: - # type: string - # example: 'COMPOSED' - # description: > - # The output mode of the recording. Possible value: "COMPOSED". - status: - type: string - example: 'ACTIVE' - description: > - The status of the recording. - Possible values: - - STARTING - - ACTIVE - - ENDING - - COMPLETE - - FAILED - - ABORTED - - LIMITED_REACHED - filename: - type: string - example: 'http://localhost:6080/meet/OpenVidu-123456/?secret=tok_123456' - description: > - The URL for the publisher to join the room. The publisher has permissions to publish audio and - video streams to the room. - viewerURL: - type: string - example: 'http://localhost:6080/meet/OpenVidu-123456/?secret=tok_123456' - description: > - The URL for the viewer to join the room. The viewer has read-only permissions to watch the room - and participants. + $ref: './components/schemas/meet-room-preferences.yaml#/MeetRoomPreferences' MeetRecording: - allOf: - - $ref: '#/components/schemas/MeetRecordingBase' - - type: object - properties: - endDate: - type: number - example: 1620000000000 - description: The date when the recording was stopped (milliseconds since the Unix epoch). - duration: - type: number - example: 3600 - description: The duration of the recording in seconds. - size: - type: number - example: 1024 - description: The size of the recording file in bytes. - errorCode: - type: number - example: 100 - description: The error code of the recording. - error: - type: [string, 'null'] - description: The error message of the recording. - details: - type: string - example: 'Stopped using API' - description: Additional details about the recording. - - MeetRecordingStart: - $ref: '#/components/schemas/MeetRecordingBase' - + $ref: components/schemas/meet-recording.yaml Error: - type: object - required: - - message - properties: - name: - type: string - message: - type: string - code: - type: integer - description: HTTP status code associated with the error + $ref: components/schemas/error.yaml + MeetWebhookEvent: + $ref: components/schemas/meet-webhook.yaml#/MeetWebhookEvent \ No newline at end of file diff --git a/backend/openapi/openvidu-meet-internal-api.yaml b/backend/openapi/openvidu-meet-internal-api.yaml index 1bbf345..edcb58f 100644 --- a/backend/openapi/openvidu-meet-internal-api.yaml +++ b/backend/openapi/openvidu-meet-internal-api.yaml @@ -1,580 +1,31 @@ openapi: 3.1.0 info: - title: OpenVidu Meet REST API - description: > - The OpenVidu Meet REST API provides a comprehensive set of endpoints for integrating real-time video - conferencing capabilities into your applications. - contact: - name: OpenVidu - email: commercial@openvidu.io - url: https://openvidu.io/support/ - license: - name: Apache License 2.0 - identifier: Apache-2.0 - url: https://www.apache.org/licenses/LICENSE-2.0 - version: v1 - termsOfService: https://openvidu.io/conditions/terms-of-service/ - + $ref: './info/info.yaml' servers: - url: /meet/internal-api/v1 description: OpenVidu Meet Internal API tags: - - name: Internal API - Authentication - description: Authentication operations - - name: Internal API - Rooms - 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 - Recordings - description: Operations related to managing OpenVidu Meet recordings + $ref: './tags/tags.yaml' paths: /auth/login: - post: - operationId: loginUser - summary: Login to OpenVidu Meet - description: > - Authenticates a user and returns an access and refresh token in cookies. - tags: - - Internal API - Authentication - requestBody: - description: User credentials - required: true - content: - application/json: - schema: - type: object - properties: - username: - type: string - example: 'admin' - description: The username of the user. - password: - type: string - example: 'password123' - description: The password of the user. - responses: - '200': - description: Successfully logged in - headers: - Set-Cookie: - description: > - The cookie containing the access token. - This cookie is used to authenticate the user in subsequent requests. - schema: - type: string - example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' - Set-Cookie-Refresh: - description: > - The cookie containing the refresh token. - 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' - content: - application/json: - schema: - type: object - properties: - message: - type: string - example: 'Login succeeded' - '404': - description: Invalid credentials - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Login failed. Invalid username or password' - '422': - description: Unprocessable Entity — The request body is invalid - content: - application/json: - schema: - type: object - properties: - error: - type: string - example: 'Unprocessable Entity' - message: - type: string - example: 'Invalid request body' - details: - type: array - items: - type: object - properties: - field: - type: string - example: 'username' - message: - type: string - example: 'Username must be at least 4 characters long' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Internal server error' + $ref: './paths/internal/auth.yaml#/~1auth~1login' /auth/logout: - post: - operationId: logoutUser - summary: Logout from OpenVidu Meet - description: > - Logs out the user and clears the access and refresh tokens from cookies. - tags: - - 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: './paths/internal/auth.yaml#/~1auth~1logout' /auth/refresh: - post: - operationId: refreshAccessToken - summary: Refresh the access token - description: > - Refreshes the access token using the refresh token. - The new access token is returned in a cookie. - tags: - - Internal API - Authentication - security: - - refreshTokenCookie: [] - responses: - '200': - description: Successfully refreshed the access token - headers: - Set-Cookie: - description: > - The cookie containing the new access token. - This cookie is used to authenticate the user in subsequent requests. - schema: - type: string - example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict' - content: - application/json: - schema: - type: object - properties: - message: - type: string - example: 'Token refreshed' - '400': - description: Bad Request — The refresh token is missing or invalid - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'No refresh token provided' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Internal server error' + $ref: './paths/internal/auth.yaml#/~1auth~1refresh' /auth/profile: - get: - operationId: getUserProfile - summary: Get user profile - description: > - Retrieves the profile information of the authenticated user. - tags: - - Internal API - Authentication - security: - - accessTokenCookie: [] - responses: - '200': - description: Successfully retrieved user profile - content: - application/json: - schema: - type: object - properties: - username: - type: string - example: 'admin' - description: The username of the authenticated user. - role: - type: string - example: 'admin' - description: The role assigned to the authenticated user. - '401': - description: Unauthorized — The access token is missing or invalid - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' + $ref: './paths/internal/auth.yaml#/~1auth~1profile' /rooms/{roomId}/participant-role: - get: - operationId: getParticipantRole - summary: Get participant role in a room - 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. - tags: - - Internal API - Rooms - security: - - accessTokenCookie: [] - parameters: - - name: roomId - in: path - required: true - description: The name of the room to check the participant's role - schema: - type: string - - name: secret - in: query - required: true - description: The secret token from the room URL to check the participant's role - schema: - type: string - 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. - '404': - description: Room not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Room Error' - message: 'The room does not exist' - '422': - description: Unprocessable Entity — Invalid request query parameters - content: - application/json: - schema: - type: object - properties: - error: - type: string - example: 'Unprocessable Entity' - message: - type: string - example: 'Invalid request query' - details: - type: array - items: - type: object - properties: - field: - type: string - example: 'secret' - message: - type: string - example: 'secret is required' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Internal server error' + $ref: './paths/internal/rooms.yaml#/~1rooms~1{roomId}~1participant-role' /recordings/{recordingId}/stream: - get: - operationId: getRecordingStream - summary: Stream an OpenVidu Meet recording - description: > - Streams the OpenVidu Meet recording with the specified recording ID. - This endpoint supports range requests, allowing partial content retrieval - for video playback without downloading the entire file. - tags: - - Internal API - Recordings - security: - - accessTokenCookie: [] - parameters: - - name: recordingId - in: path - required: true - description: The ID of the recording to stream - schema: - type: string - - name: Range - in: header - required: false - description: > - Byte range for partial content retrieval. - Example: `bytes=0-1023` to request the first 1024 bytes of the file. - schema: - type: string - responses: - '200': - description: Successfully streaming the full recording - headers: - Accept-Ranges: - description: Indicates that byte-range requests are supported - schema: - type: string - Content-Length: - description: The total file size in bytes - schema: - type: integer - content: - video/mp4: - schema: - type: string - format: binary - '206': - description: Partial content streaming based on byte range - headers: - Accept-Ranges: - description: Indicates that byte-range requests are supported - schema: - type: string - Content-Range: - description: Specifies the range of bytes being sent - schema: - type: string - Content-Length: - description: The length of the partial content in bytes - schema: - type: integer - content: - video/mp4: - schema: - type: string - format: binary - '400': - description: Bad Request — Invalid range header format - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 400 - message: 'Invalid Range header' - '401': - description: Unauthorized — The access token is missing or invalid - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Recording not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 404 - message: 'Recording not found' - '416': - description: Requested range not satisfiable - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 416 - message: 'Requested range not satisfiable' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - code: 500 - message: 'Internal server error' + $ref: './paths/internal/recordings.yaml#/~1recordings~1{recordingId}~1stream' /participants/token: - post: - operationId: generateParticipantToken - summary: Generate a token for a participant - description: > - Generates a token for a participant to join an OpenVidu Meet room. - tags: - - Internal API - Participant - security: - - accessTokenCookie: [] - requestBody: - description: Participant details - content: - application/json: - schema: - $ref: '#/components/schemas/TokenOptions' - responses: - '200': - description: Successfully generated the participant token - headers: - Set-Cookie: - description: > - The cookie containing the participant token. - This cookie is used to authenticate the participant in the room. - schema: - type: string - example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' - content: - application/json: - schema: - type: object - properties: - token: - type: string - example: 'token_123456' - description: > - The token to authenticate the participant. - '401': - description: Unauthorized — The access token is missing or invalid when authentication is required - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions when authentication is required - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Room not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Room Error' - message: 'The room does not exist' - '409': - description: Conflict — The participant already exists in the room - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Participant Error' - message: 'Participant already exists in the room' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Internal server error' + $ref: './paths/internal/participants.yaml#/~1participants~1token' /participants/token/refresh: - post: - operationId: refreshParticipantToken - summary: Refresh a token for a participant - description: > - Refresh a token for a participant in an OpenVidu Meet room. - tags: - - Internal API - Participant - security: - - accessTokenCookie: [] - requestBody: - description: Participant details - content: - application/json: - schema: - $ref: '#/components/schemas/TokenOptions' - responses: - '200': - description: Successfully refreshed the participant token - headers: - Set-Cookie: - description: > - The cookie containing the participant token. - This cookie is used to authenticate the participant in the room. - schema: - type: string - example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' - content: - application/json: - schema: - type: object - properties: - token: - type: string - example: 'token_123456' - description: > - The token to authenticate the participant. - '401': - description: Unauthorized — The access token is missing or invalid when authentication is required - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Unauthorized' - '403': - description: Forbidden — The user authenticated with the access token does not have enough permissions when authentication is required - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Insufficient permissions to access this resource' - '404': - description: Room or participant not found - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - name: 'Participant Error' - message: 'Participant not found in the room' - '409': - description: Conflict — Current token is still valid - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Participant token is still valid' - '500': - description: Internal server error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - example: - message: 'Internal server error' + $ref: './paths/internal/participants.yaml#/~1participants~1token~1refresh' /participants/{participantName}: + $ref: './paths/internal/participants.yaml#/~1participants~1{participantName}' delete: operationId: disconnectParticipant summary: Delete a participant from a room @@ -637,124 +88,17 @@ paths: components: securitySchemes: - accessTokenCookie: - type: apiKey - name: OvMeetAccessToken - in: cookie - description: > - The JWT token to authenticate the request in case of consuming the API from the OpenVidu Meet frontend. - refreshTokenCookie: - type: apiKey - name: OvMeetRefreshToken - in: cookie - description: > - The JWT token to refresh the access token in case of consuming the API from the OpenVidu Meet frontend. - participantTokenCookie: - type: apiKey - name: OvMeetParticipantToken - in: cookie - description: > - The JWT token to authenticate the participant when entering the room. + $ref: './components/security.yaml' schemas: - MeetRecordingBase: - type: object - properties: - recordingId: - type: string - example: 'room-123--EG_XYZ--XX445' - description: The unique identifier of the recording. - roomId: - type: string - example: 'room-123' - description: The ID of the room where the recording was made. - # outputMode: - # type: string - # example: 'COMPOSED' - # description: > - # The output mode of the recording. Possible value: "COMPOSED". - status: - type: string - example: 'ACTIVE' - description: > - The status of the recording. - Possible values: - - STARTING - - ACTIVE - - ENDING - - COMPLETE - - FAILED - - ABORTED - - LIMITED_REACHED - filename: - type: string - example: 'room-123--XX445.mp4' - description: The name of the recording file. - startDate: - type: number - example: 1620000000000 - description: The date when the recording was started (milliseconds since the Unix epoch). - + MeetRoom: + $ref: components/schemas/meet-room.yaml + MeetRoomOptions: + $ref: components/schemas/meet-room-options.yaml + MeetRoomPreferences: + $ref: './components/schemas/meet-room-preferences.yaml#/MeetRoomPreferences' MeetRecording: - allOf: - - $ref: '#/components/schemas/MeetRecordingBase' - - type: object - properties: - endDate: - type: number - example: 1620000000000 - description: The date when the recording was stopped (milliseconds since the Unix epoch). - duration: - type: number - example: 3600 - description: The duration of the recording in seconds. - size: - type: number - example: 1024 - description: The size of the recording file in bytes. - errorCode: - type: number - example: 100 - description: The error code of the recording. - error: - type: [string, 'null'] - description: The error message of the recording. - details: - type: string - example: 'Stopped using API' - description: Additional details about the recording. - - MeetRecordingStart: - $ref: '#/components/schemas/MeetRecordingBase' - - TokenOptions: - type: object - required: - - roomId - - participantName - - secret - properties: - roomId: - type: string - example: 'room-123' - description: > - The ID of the room where the participant will join. - participantName: - type: string - example: 'Alice' - description: > - The name of the participant. - secret: - type: string - example: 'abc123456' - description: > - The secret token from the room Url - + $ref: components/schemas/meet-recording.yaml Error: - type: object - required: - - message - properties: - name: - type: string - message: - type: string + $ref: components/schemas/error.yaml + MeetWebhookEvent: + $ref: components/schemas/meet-webhook.yaml#/MeetWebhookEvent diff --git a/backend/openapi/paths/internal/auth.yaml b/backend/openapi/paths/internal/auth.yaml new file mode 100644 index 0000000..ec7181e --- /dev/null +++ b/backend/openapi/paths/internal/auth.yaml @@ -0,0 +1,78 @@ +/auth/login: + post: + operationId: loginUser + summary: Login to OpenVidu Meet + description: > + Authenticates a user and returns an access and refresh token in cookies. + tags: + - Internal API - Authentication + requestBody: + $ref: '../../components/requestBodies/internal/login-user.yaml' + responses: + '200': + $ref: '../../components/responses/internal/success-user-login.yaml' + # Should be 401 + '404': + $ref: '../../components/responses/internal/error-invalid-credentials.yaml' + '422': + $ref: '../../components/responses/validation-error.yaml' + '500': + $ref: '../../components/responses/internal-server-error.yaml' +/auth/logout: + post: + operationId: logoutUser + summary: Logout from OpenVidu Meet + description: > + Logs out the user and clears the access and refresh tokens from cookies. + tags: + - Internal API - Authentication + responses: + '200': + $ref: '../../components/responses/internal/success-user-logout.yaml' + +/auth/refresh: + post: + operationId: refreshAccessToken + summary: Refresh the access token + description: > + Refreshes the access token using the refresh token. + The new access token is returned in a cookie. + tags: + - Internal API - Authentication + security: + - refreshTokenCookie: [] + responses: + '200': + $ref: '../../components/responses/internal/success-refresh-token.yaml' + '400': + $ref: '../../components/responses/internal/error-invalid-refresh-token.yaml' + '500': + $ref: '../../components/responses/internal-server-error.yaml' +/auth/profile: + get: + operationId: getUserProfile + summary: Get user profile + description: > + Retrieves the profile information of the authenticated user. + tags: + - Internal API - Authentication + security: + - accessTokenCookie: [] + responses: + '200': + description: Successfully retrieved user profile + content: + application/json: + schema: + type: object + properties: + username: + type: string + example: 'admin' + description: The username of the authenticated user. + role: + type: string + example: 'admin' + description: The role assigned to the authenticated user. + '401': + $ref: '../../components/responses/internal/error-invalid-refresh-token.yaml' diff --git a/backend/openapi/paths/internal/participants.yaml b/backend/openapi/paths/internal/participants.yaml new file mode 100644 index 0000000..bb4e0c1 --- /dev/null +++ b/backend/openapi/paths/internal/participants.yaml @@ -0,0 +1,125 @@ +/participants/token: + post: + operationId: generateParticipantToken + summary: Generate a token for a participant + description: > + Generates a token for a participant to join an OpenVidu Meet room. + tags: + - Internal API - Participant + security: + - accessTokenCookie: [] + requestBody: + $ref: '../../components/requestBodies/internal/participant-token-request.yaml' + responses: + '200': + description: Successfully generated the participant token + headers: + Set-Cookie: + description: > + The cookie containing the participant token. + This cookie is used to authenticate the participant in the room. + schema: + type: string + example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' + content: + application/json: + schema: + type: object + properties: + token: + type: string + example: 'token_123456' + description: > + The token to authenticate the participant. + '401': + $ref: '../../components/responses/unauthorized-error.yaml' + '403': + $ref: '../../components/responses/forbidden-error.yaml' + + '404': + $ref: '../../components/responses/error-room-not-found.yaml' + '409': + description: Conflict — The participant already exists in the room + content: + application/json: + schema: + $ref: '../../components/schemas/error.yaml' + example: + name: 'Participant Error' + message: 'Participant already exists in the room' + '500': + $ref: '../../components/responses/internal-server-error.yaml' + +/participants/token/refresh: + post: + operationId: refreshParticipantToken + summary: Refresh a token for a participant + description: > + Refresh a token for a participant in an OpenVidu Meet room. + tags: + - Internal API - Participant + security: + - accessTokenCookie: [] + requestBody: + $ref: '../../components/requestBodies/internal/participant-token-request.yaml' + responses: + '200': + description: Successfully refreshed the participant token + headers: + Set-Cookie: + description: > + The cookie containing the participant token. + This cookie is used to authenticate the participant in the room. + schema: + type: string + example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict' + content: + application/json: + schema: + type: object + properties: + token: + type: string + example: 'token_123456' + description: > + The token to authenticate the participant. + '401': + $ref: '../../components/responses/unauthorized-error.yaml' + '403': + $ref: '../../components/responses/forbidden-error.yaml' + '404': + $ref: '../../components/responses/error-room-not-found.yaml' + '409': + description: Conflict — Current token is still valid + content: + application/json: + schema: + $ref: '../../components/schemas/error.yaml' + example: + message: 'Participant token is still valid' + '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/internal/participant-name.yaml' + - $ref: '../../components/parameters/room-id.yaml' + responses: + '204': + description: Successfully disconnect the participant + '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' diff --git a/backend/openapi/paths/internal/recordings.yaml b/backend/openapi/paths/internal/recordings.yaml new file mode 100644 index 0000000..c90ed1c --- /dev/null +++ b/backend/openapi/paths/internal/recordings.yaml @@ -0,0 +1,78 @@ +/recordings/{recordingId}/stream: + get: + operationId: getRecordingStream + summary: Stream an OpenVidu Meet recording + description: > + Streams the OpenVidu Meet recording with the specified recording ID. + This endpoint supports range requests, allowing partial content retrieval + for video playback without downloading the entire file. + tags: + - Internal API - Recordings + security: + - accessTokenCookie: [] + parameters: + - $ref: '../../components/parameters/recording-id.yaml' + - $ref: '../../components/parameters/recording-range.yaml' + responses: + '200': + description: Successfully streaming the full recording + headers: + Accept-Ranges: + description: Indicates that byte-range requests are supported + schema: + type: string + Content-Length: + description: The total file size in bytes + schema: + type: integer + content: + video/mp4: + schema: + type: string + format: binary + '206': + description: Partial content streaming based on byte range + headers: + Accept-Ranges: + description: Indicates that byte-range requests are supported + schema: + type: string + Content-Range: + description: Specifies the range of bytes being sent + schema: + type: string + Content-Length: + description: The length of the partial content in bytes + schema: + type: integer + content: + video/mp4: + schema: + type: string + format: binary + '400': + description: Bad Request — Invalid range header format + content: + application/json: + schema: + $ref: '../../components/schemas/error.yaml' + example: + code: 400 + message: 'Invalid Range header' + '401': + $ref: '../../components/responses/unauthorized-error.yaml' + '403': + $ref: '../../components/responses/forbidden-error.yaml' + '404': + $ref: '../../components/responses/error-room-not-found.yaml' + '416': + description: Requested range not satisfiable + content: + application/json: + schema: + $ref: '../../components/schemas/error.yaml' + example: + code: 416 + message: 'Requested range not satisfiable' + '500': + $ref: '../../components/responses/internal-server-error.yaml' diff --git a/backend/openapi/paths/internal/rooms.yaml b/backend/openapi/paths/internal/rooms.yaml new file mode 100644 index 0000000..3c74f15 --- /dev/null +++ b/backend/openapi/paths/internal/rooms.yaml @@ -0,0 +1,29 @@ +/rooms/{roomId}/participant-role: + get: + operationId: getParticipantRole + summary: Get participant role in a room + 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. + 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. + '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/paths/recordings.yaml b/backend/openapi/paths/recordings.yaml new file mode 100644 index 0000000..5d9137d --- /dev/null +++ b/backend/openapi/paths/recordings.yaml @@ -0,0 +1,180 @@ +/recordings: + post: + operationId: createRecording + summary: Start a recording + description: > + Start a new recording for an OpenVidu Meet room with the specified room ID. + tags: + - OpenVidu Meet - Recordings + security: + - participantTokenCookie: [] + requestBody: + $ref: '../components/requestBodies/start-recording-request.yaml' + responses: + '200': + $ref: '../components/responses/success-start-recording.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-recording-already-started.yaml' + '422': + $ref: '../components/responses/validation-error.yaml' + '500': + $ref: '../components/responses/internal-server-error.yaml' + get: + operationId: getRecordings + summary: Get all recordings + 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. + tags: + - OpenVidu Meet - Recordings + security: + - apiKeyInHeader: [] + - accessTokenCookie: [] + 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/room-id.yaml' + - $ref: '../components/parameters/max-items.yaml' + - $ref: '../components/parameters/next-page-token.yaml' + responses: + '200': + $ref: '../components/responses/success-get-recordings.yaml' + '401': + $ref: '../components/responses/unauthorized-error.yaml' + '403': + $ref: '../components/responses/forbidden-error.yaml' + '500': + $ref: '../components/responses/internal-server-error.yaml' + + delete: + operationId: bulkDeleteRecordings + summary: Bulk delete recordings + description: > + Deletes multiple recordings at once with the specified recording IDs. + tags: + - OpenVidu Meet - Recordings + security: + - apiKeyInHeader: [] + - accessTokenCookie: [] + parameters: + - name: recordingIds + in: query + required: true + description: | + The unique IDs of the recordings to delete. + You can provide multiple recording IDs as a comma-separated list (e.g., `recordingIds=room-123--EG_XYZ--XX445,room-123--EG_XYZ--XX446`). + schema: + type: string + responses: + '200': + $ref: '../components/responses/success-bulk-delete-recordings.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' + +/recordings/{recordingId}: + put: + operationId: stopRecording + summary: Stop a recording + description: > + Stops a recording with the specified recording ID. + The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned. + tags: + - OpenVidu Meet - Recordings + security: + - participantTokenCookie: [] + parameters: + - $ref: '../components/parameters/recording-id.yaml' + responses: + '200': + $ref: '../components/responses/success-stop-recording.yaml' + '401': + $ref: '../components/responses/unauthorized-error.yaml' + '403': + $ref: '../components/responses/forbidden-error.yaml' + '404': + $ref: '../components/responses/error-recording-not-found.yaml' + '409': + $ref: '../components/responses/error-recording-in-progress.yaml' + '500': + $ref: '../components/responses/internal-server-error.yaml' + + get: + operationId: getRecording + summary: Get a recording + description: > + Retrieves the details of a recording with the specified recording ID. + tags: + - OpenVidu Meet - Recordings + security: + - apiKeyInHeader: [] + - accessTokenCookie: [] + parameters: + - $ref: '../components/parameters/recording-id.yaml' + responses: + '200': + $ref: '../components/responses/success-get-recording.yaml' + '401': + $ref: '../components/responses/unauthorized-error.yaml' + '403': + $ref: '../components/responses/forbidden-error.yaml' + '404': + $ref: '../components/responses/error-recording-not-found.yaml' + '500': + $ref: '../components/responses/internal-server-error.yaml' + 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`). + tags: + - OpenVidu Meet - Recordings + security: + - apiKeyInHeader: [] + - accessTokenCookie: [] + parameters: + - $ref: '../components/parameters/recording-id.yaml' + responses: + '204': + description: Recording successfully deleted. No content is returned. + '401': + $ref: '../components/responses/unauthorized-error.yaml' + '403': + $ref: '../components/responses/forbidden-error.yaml' + '404': + $ref: '../components/responses/error-recording-not-found.yaml' + '409': + $ref: '../components/responses/error-recording-in-progress.yaml' + '500': + $ref: '../components/responses/internal-server-error.yaml' diff --git a/backend/openapi/paths/rooms.yaml b/backend/openapi/paths/rooms.yaml new file mode 100644 index 0000000..8040776 --- /dev/null +++ b/backend/openapi/paths/rooms.yaml @@ -0,0 +1,132 @@ +/rooms: + post: + operationId: createRoom + summary: Create a room + description: > + Creates a new OpenVidu Meet room with the specified expiration date. + The room will be available for participants to join using the generated URLs. + tags: + - OpenVidu Meet - Room + security: + - apiKeyInHeader: [] + - accessTokenCookie: [] + requestBody: + $ref: '../components/requestBodies/create-room-request.yaml' + responses: + '200': + $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 all rooms available in the system. + tags: + - OpenVidu Meet - Room + security: + - apiKeyInHeader: [] + - accessTokenCookie: [] + parameters: + - $ref: '../components/parameters/max-items.yaml' + - $ref: '../components/parameters/next-page-token.yaml' + responses: + '200': + $ref: '../components/responses/success-get-rooms.yaml' + '401': + $ref: '../components/responses/unauthorized-error.yaml' + '403': + $ref: '../components/responses/forbidden-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. + tags: + - OpenVidu Meet - Room + security: + - apiKeyInHeader: [] + - accessTokenCookie: [] + - participantTokenCookie: [] + parameters: + - $ref: '../components/parameters/room-id.yaml' + responses: + '200': + $ref: '../components/responses/success-create-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' + '500': + $ref: '../components/responses/internal-server-error.yaml' + put: + operationId: updateRoom + summary: Update a room + description: > + Updates the preferences of an OpenVidu Meet room with the specified room ID. + tags: + - OpenVidu Meet - Room + security: + - apiKeyInHeader: [] + - accessTokenCookie: [] + parameters: + - name: roomId + in: path + required: true + description: The unique identifier of the room to update + schema: + type: string + example: 'room-123' + requestBody: + $ref: '../components/requestBodies/update-room-request.yaml' + responses: + '200': + $ref: '../components/responses/success-create-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 an OpenVidu Meet room with the specified room ID. + The room with participants will be closed and all participants will be disconnected. + The room will be deleted from the system and will no longer be available. + tags: + - OpenVidu Meet - Room + security: + - apiKeyInHeader: [] + - accessTokenCookie: [] + parameters: + - $ref: '../components/parameters/room-id.yaml' + responses: + '204': + description: Successfully deleted the OpenVidu Meet room + '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' diff --git a/backend/openapi/tags/tags.yaml b/backend/openapi/tags/tags.yaml new file mode 100644 index 0000000..54ddf68 --- /dev/null +++ b/backend/openapi/tags/tags.yaml @@ -0,0 +1,12 @@ +- name: OpenVidu Meet - Room + description: Operations related to managing OpenVidu Meet rooms +- name: OpenVidu Meet - Recordings + description: Operations related to managing OpenVidu Meet recordings +- name: Internal API - Authentication + description: Authentication operations +- name: Internal API - Rooms + 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 - Recordings + description: Operations related to managing OpenVidu Meet recordings diff --git a/backend/openapi/webhooks/webhooks.yaml b/backend/openapi/webhooks/webhooks.yaml new file mode 100644 index 0000000..85818bb --- /dev/null +++ b/backend/openapi/webhooks/webhooks.yaml @@ -0,0 +1,161 @@ +recordingStarted: + post: + summary: Recording started + description: > + This webhook is triggered when a recording starts. + The API provider will send a POST request to this endpoint with the recording details. + The JSON payload includes information such as the recording identifier, room, and its status. + operationId: recordingStartedWebhook + parameters: + - name: X-Timestamp + in: header + description: Timestamp of the webhook event (in Unix Epoch seconds) + example: 1678901234 + schema: + type: string + - name: X-Signature + in: header + description: HMAC signature for webhook verification + example: 1234567890abcdef + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + # $ref: '#/components/schemas/RecordingStartedWebhook' + 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: recordingStarted + data: + type: object + properties: + recordingId: + type: string + description: The unique identifier of the recording that started. + example: room-123--EG_XYZ--XX445 + roomId: + type: string + description: The unique identifier of the room for which the recording started. + example: room-123 + status: + type: string + description: The status of the recording. + example: STARTING + responses: + '200': + description: Webhook received successfully +# recordingUpdated: +# post: +# summary: Recording updated +# description: > +# This webhook is triggered when a recording update occurs. +# The API provider sends a POST request with the updated details of the recording. +# operationId: recordingUpdatedWebhook +# parameters: +# - name: X-Timestamp +# in: header +# description: Timestamp of the webhook event (in Unix Epoch seconds) +# example: 1678901234 +# schema: +# type: string +# - name: X-Signature +# in: header +# description: HMAC signature for webhook verification +# example: 1234567890abcdef +# schema: +# type: string +# requestBody: +# required: true +# content: +# application/json: +# schema: +# type: object +# 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: recordingUpdated +# data: +# type: object +# properties: +# recordingId: +# type: string +# description: The unique identifier of the recording being updated. +# example: room-123--EG_XYZ--XX445 +# roomId: +# type: string +# description: The unique identifier of the room for which the recording is updated. +# example: room-123 +# status: +# type: string +# description: The updated status of the recording. +# example: ACTIVE +# responses: +# '200': +# description: Webhook received successfully + +# recordingEnded: +# post: +# summary: Recording ended +# description: > +# This webhook is triggered when a recording ends. +# The API provider will send a POST request containing the final details of the recording. +# operationId: recordingEndedWebhook +# parameters: +# - name: X-Timestamp +# in: header +# description: Timestamp of the webhook event (in Unix Epoch seconds) +# example: 1678901234 +# schema: +# type: string +# - name: X-Signature +# in: header +# description: HMAC signature for webhook verification +# example: 1234567890abcdef +# schema: +# type: string +# requestBody: +# required: true +# content: +# application/json: +# schema: +# type: object +# 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: recordingEnded +# data: +# type: object +# properties: +# recordingId: +# type: string +# description: The unique identifier of the recording that ended. +# example: room-123--EG_XYZ--XX445 +# roomId: +# type: string +# description: The unique identifier of the room for which the recording ended. +# example: room-123 +# status: +# type: string +# description: The final status of the recording. +# example: COMPLETE +# responses: +# '200': +# description: Webhook received successfully diff --git a/backend/package.json b/backend/package.json index 866d57b..2fa61eb 100644 --- a/backend/package.json +++ b/backend/package.json @@ -29,8 +29,8 @@ "scripts": { "build:prod": "tsc", "postbuild:prod": "npm run doc:api && npm run doc:internal-api", - "doc:api": "mkdir -p public/openapi && npx openapi-generate-html -i openapi/openvidu-meet-api.yaml --ui=stoplight --theme=light --title 'OpenVidu Meet REST API' --description 'OpenVidu Meet REST API' -o public/openapi/public.html", - "doc:internal-api": "mkdir -p public/openapi && npx openapi-generate-html -i openapi/openvidu-meet-internal-api.yaml --ui=stoplight --theme=dark --title 'OpenVidu Meet Internal REST API' --description 'OpenVidu Meet Internal REST API' -o public/openapi/internal.html", + "doc:api": "mkdir -p public/openapi && cd openapi && npx openapi-generate-html -i openvidu-meet-api.yaml --ui=stoplight --theme=light --title 'OpenVidu Meet REST API' --description 'OpenVidu Meet REST API' -o ../public/openapi/public.html", + "doc:internal-api": "mkdir -p public/openapi && cd openapi && npx openapi-generate-html -i openvidu-meet-internal-api.yaml --ui=stoplight --theme=dark --title 'OpenVidu Meet Internal REST API' --description 'OpenVidu Meet Internal REST API' -o ../public/openapi/internal.html", "start:prod": "node dist/src/server.js", "start:dev": "nodemon", "package:build": "npm run build:prod && npm pack",