215b11e93f
This commit refactors the recording API endpoints from the internal API to the public API. This change allows users to start and stop recordings using API keys, enabling more secure and flexible access control for recording functionality. It also centralizes recording-related logic in the public API, simplifying the codebase and improving maintainability.
344 lines
14 KiB
YAML
344 lines
14 KiB
YAML
/recordings:
|
|
post:
|
|
operationId: startRecording
|
|
summary: Start a recording
|
|
description: >
|
|
Start a new recording for an OpenVidu Meet room with the specified room ID.
|
|
tags:
|
|
- OpenVidu Meet - Recordings
|
|
security:
|
|
- apiKeyHeader: []
|
|
- roomMemberTokenHeader: []
|
|
requestBody:
|
|
$ref: '../components/requestBodies/start-recording-request.yaml'
|
|
responses:
|
|
'201':
|
|
$ref: '../components/responses/success-start-recording.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-not-allowed-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-room-not-found.yaml'
|
|
'409':
|
|
$ref: '../components/responses/error-recording-conflict.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
'503':
|
|
$ref: '../components/responses/error-service-unavailable.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.
|
|
|
|
By default, the recordings are sorted by start date in descending order (newest first).
|
|
|
|
> **Note:** If this endpoint is called using the `roomMemberTokenHeader` authentication method,
|
|
> the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned.
|
|
tags:
|
|
- OpenVidu Meet - Recordings
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/room-id-query.yaml'
|
|
- $ref: '../components/parameters/room-name.yaml'
|
|
- $ref: '../components/parameters/recording-status.yaml'
|
|
- $ref: '../components/parameters/recording-fields.yaml'
|
|
- $ref: '../components/parameters/max-items.yaml'
|
|
- $ref: '../components/parameters/next-page-token.yaml'
|
|
- $ref: '../components/parameters/sort-field.yaml'
|
|
- $ref: '../components/parameters/sort-order.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-get-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'
|
|
|
|
delete:
|
|
operationId: bulkDeleteRecordings
|
|
summary: Bulk delete recordings
|
|
description: |
|
|
Deletes multiple recordings at once with the specified recording IDs.
|
|
|
|
> **Note:** If this endpoint is called using the `roomMemberTokenHeader` authentication method,
|
|
> all specified recordings must belong to the same room included in the token.
|
|
> If a recording does not belong to that room, it will not be deleted.
|
|
tags:
|
|
- OpenVidu Meet - Recordings
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/recording-ids.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-bulk-delete-recordings.yaml'
|
|
'400':
|
|
$ref: '../components/responses/error-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/download:
|
|
get:
|
|
operationId: downloadRecordings
|
|
summary: Download recordings
|
|
description: |
|
|
Downloads multiple recordings as a ZIP file with the specified recording IDs.
|
|
The ZIP file will contain all recordings in MP4 format.
|
|
|
|
> **Note:** If this endpoint is called using the `roomMemberTokenHeader` authentication method,
|
|
> all specified recordings must belong to the same room included in the token.
|
|
> If a recording does not belong to that room, it will not be included in the ZIP file.
|
|
tags:
|
|
- OpenVidu Meet - Recordings
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/recording-ids.yaml'
|
|
responses:
|
|
'200':
|
|
description: Successfully created a ZIP file containing the requested recordings
|
|
headers:
|
|
Content-Disposition:
|
|
description: >
|
|
Indicates that the response is a file download.
|
|
The filename will be `recordings.zip`.
|
|
schema:
|
|
type: string
|
|
example: attachment; filename="recordings.zip"
|
|
content:
|
|
application/zip:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'400':
|
|
$ref: '../components/responses/error-recordings-not-same-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'
|
|
|
|
/recordings/{recordingId}:
|
|
get:
|
|
operationId: getRecording
|
|
summary: Get a recording
|
|
description: >
|
|
Retrieves the details of a recording with the specified recording ID.
|
|
tags:
|
|
- OpenVidu Meet - Recordings
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/recording-id.yaml'
|
|
- $ref: '../components/parameters/recording-secret.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-get-recording.yaml'
|
|
'400':
|
|
$ref: '../components/responses/error-invalid-recording-secret.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-recording-not-found.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
delete:
|
|
operationId: deleteRecording
|
|
summary: Delete a recording
|
|
description: |
|
|
Deletes a recording with the specified recording ID.
|
|
|
|
> ⚠️ **Note:** The recording will only be deleted if it exists and is not in progress
|
|
> (i.e., not in a state such as `active`, `starting`, or `ending`).
|
|
tags:
|
|
- OpenVidu Meet - Recordings
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/recording-id.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-delete-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'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
/recordings/{recordingId}/media:
|
|
get:
|
|
operationId: getRecordingMedia
|
|
summary: Get recording media
|
|
description: |
|
|
Retrieves the media of a recording with the specified recording ID.
|
|
The media is returned in a binary format suitable for video playback.
|
|
|
|
This endpoint supports range requests, allowing partial content retrieval
|
|
for video playback without downloading the entire file.
|
|
tags:
|
|
- OpenVidu Meet - Recordings
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/recording-id.yaml'
|
|
- $ref: '../components/parameters/recording-secret.yaml'
|
|
- $ref: '../components/parameters/recording-range.yaml'
|
|
responses:
|
|
'200':
|
|
description: Successfully retrieved the full recording media
|
|
headers:
|
|
Accept-Ranges:
|
|
$ref: '../components/headers/accept-ranges.yaml'
|
|
Content-Length:
|
|
$ref: '../components/headers/content-length.yaml'
|
|
Cache-Control:
|
|
$ref: '../components/headers/cache-control.yaml'
|
|
content:
|
|
video/mp4:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'206':
|
|
description: Successfully retrieved a partial range of the recording media
|
|
headers:
|
|
Accept-Ranges:
|
|
$ref: '../components/headers/accept-ranges.yaml'
|
|
Content-Length:
|
|
$ref: '../components/headers/content-length.yaml'
|
|
Cache-Control:
|
|
$ref: '../components/headers/cache-control.yaml'
|
|
Content-Range:
|
|
$ref: '../components/headers/content-range.yaml'
|
|
content:
|
|
video/mp4:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'400':
|
|
$ref: '../components/responses/error-invalid-recording-secret.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'
|
|
'416':
|
|
description: Requested range not satisfiable
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '../components/schemas/error.yaml'
|
|
example:
|
|
error: Recording Error
|
|
message: 'Recording "room-123--EG_XYZ--XX445" range not satisfiable. File size: 123456789'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
/recordings/{recordingId}/stop:
|
|
post:
|
|
operationId: stopRecording
|
|
summary: Stop a recording
|
|
description: |
|
|
Stops a recording with the specified recording ID.
|
|
|
|
> **Note:** The recording must be in an `active` state; otherwise, a 409 error is returned.
|
|
tags:
|
|
- OpenVidu Meet - Recordings
|
|
security:
|
|
- apiKeyHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/recording-id.yaml'
|
|
responses:
|
|
'202':
|
|
$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-not-active.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|
|
/recordings/{recordingId}/url:
|
|
get:
|
|
operationId: getRecordingUrl
|
|
summary: Get recording URL
|
|
description: |
|
|
Retrieves the URL of a recording with the specified recording ID.
|
|
This URL is intended to be shared with people who do not have direct access to the recording.
|
|
|
|
# It can be configured to be accessible by anyone (public access) or restricted to authenticated users only,
|
|
# depending on the `privateAccess` query parameter.
|
|
tags:
|
|
- OpenVidu Meet - Recordings
|
|
security:
|
|
- apiKeyHeader: []
|
|
- accessTokenHeader: []
|
|
- roomMemberTokenHeader: []
|
|
parameters:
|
|
- $ref: '../components/parameters/recording-id.yaml'
|
|
# - $ref: '../components/parameters/private-access.yaml'
|
|
responses:
|
|
'200':
|
|
$ref: '../components/responses/success-get-recording-url.yaml'
|
|
'401':
|
|
$ref: '../components/responses/unauthorized-error.yaml'
|
|
'403':
|
|
$ref: '../components/responses/forbidden-error.yaml'
|
|
'404':
|
|
$ref: '../components/responses/error-recording-not-found.yaml'
|
|
'422':
|
|
$ref: '../components/responses/validation-error.yaml'
|
|
'500':
|
|
$ref: '../components/responses/internal-server-error.yaml'
|