Refactor OpenAPI documentation for clarity and consistency
This commit is contained in:
juancarmore
parent
83b468b8cb
commit
4ca7f82d15
@ -1,4 +1,5 @@
|
||||
description: Indicates that the server supports range requests for content retrieval
|
||||
description: >
|
||||
Specifies that the server allows clients to request specific ranges of content, enabling partial retrieval of resources.
|
||||
schema:
|
||||
type: string
|
||||
example: bytes
|
||||
|
||||
@ -3,4 +3,4 @@ description: >
|
||||
This cookie is used to authenticate the user in subsequent requests.
|
||||
schema:
|
||||
type: string
|
||||
example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
||||
example: 'OvMeetAccessToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
||||
|
||||
@ -3,4 +3,4 @@ description: >
|
||||
This cookie is used to authenticate the participant in the room.
|
||||
schema:
|
||||
type: string
|
||||
example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
||||
example: 'OvMeetParticipantToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
||||
|
||||
@ -3,4 +3,4 @@ description: >
|
||||
This cookie is used to access the recordings in a room.
|
||||
schema:
|
||||
type: string
|
||||
example: 'OvMeetRecordingToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
||||
example: 'OvMeetRecordingToken=token_123456; Path=/; HttpOnly; SameSite=Strict'
|
||||
|
||||
@ -3,4 +3,4 @@ description: >
|
||||
This cookie is used to refresh the access token when it expires.
|
||||
schema:
|
||||
type: string
|
||||
example: 'OvMeetRefreshToken=token_123456; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
|
||||
example: 'OvMeetRefreshToken=token_123456; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
|
||||
|
||||
@ -5,5 +5,4 @@ description: >
|
||||
This will immediately disconnect all participants and remove the room.
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
example: 'true'
|
||||
type: boolean
|
||||
|
||||
@ -4,4 +4,4 @@ required: true
|
||||
description: The name of the participant.
|
||||
schema:
|
||||
type: string
|
||||
example: 'Alice'
|
||||
example: 'Alice'
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
name: maxItems
|
||||
in: query
|
||||
required: false
|
||||
description: The number of rooms per page (default is 10). Maximum is 100.
|
||||
description: Specifies the maximum number of items to return per page. The default value is 10, and the maximum allowed is 100.
|
||||
schema:
|
||||
type: integer
|
||||
default: 10
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
name: nextPageToken
|
||||
in: query
|
||||
required: false
|
||||
description: The token to retrieve the next page of elements.
|
||||
description: A token used for pagination to fetch the next set of items in a multi-page response.
|
||||
schema:
|
||||
type: string
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
name: privateAcess
|
||||
in: query
|
||||
description: >
|
||||
Indicates whether the retrieved recording URL should be configured for private access, i.e., the URL will be accessible only to authenticated users.
|
||||
Specifies if the recording URL should be restricted to private access,
|
||||
meaning only authenticated users can view or download the recording.
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
example: 'true'
|
||||
type: boolean
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
name: fields
|
||||
in: query
|
||||
description: >
|
||||
The fields to retrieve from the recording.
|
||||
Comma-separated list of fields to include in the response.
|
||||
Specifies which fields to include in the response for the recording resource.
|
||||
Provide a comma-separated list of field names.
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
example: 'recordingId,roomId'
|
||||
example: 'recordingId,roomId'
|
||||
|
||||
@ -4,4 +4,4 @@ required: true
|
||||
description: The unique identifier of the recording.
|
||||
schema:
|
||||
type: string
|
||||
example: 'room-123--EG_XYZ--XX445'
|
||||
example: 'room-123--EG_XYZ--XX445'
|
||||
|
||||
@ -3,9 +3,8 @@ in: query
|
||||
required: true
|
||||
description: >
|
||||
A comma-separated list of recording IDs.
|
||||
<br>
|
||||
Each recording ID should be in the format 'roomId--egressId--uid'
|
||||
Each recording ID must follow the format: `{roomId}--{egressId}--{uid}`.
|
||||
|
||||
schema:
|
||||
type: string
|
||||
example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446'
|
||||
example: 'room-123--EG_XYZ--XX445,room-123--EG_ZYX--XX446'
|
||||
|
||||
@ -1,11 +1,14 @@
|
||||
name: Range
|
||||
in: header
|
||||
required: false
|
||||
description: >
|
||||
This endpoint accepts a `Range` header to specify the byte range of the recording file to be streamed.
|
||||
The format of the `Range` header should be `bytes=start-end`, where `start` is required and `end` is optional.
|
||||
For example,
|
||||
- `bytes=0-1023` to request the first 1024 bytes of the file.
|
||||
- `bytes=1000-` to request from byte 1000 to the end of the file.
|
||||
description: |
|
||||
This endpoint supports the `Range` header to request a specific byte range of the recording file.
|
||||
Use the format `bytes=start-end`, where `start` is the starting byte (required) and `end` is the ending byte (optional).
|
||||
|
||||
Examples:
|
||||
- `bytes=0-1023`: Requests bytes 0 through 1023 (first 1024 bytes).
|
||||
- `bytes=1000-`: Requests from byte 1000 to the end of the file.
|
||||
|
||||
This allows efficient partial downloads and resume capabilities for large files.
|
||||
schema:
|
||||
type: string
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
name: secret
|
||||
in: query
|
||||
required: false
|
||||
description: The secret value used to access the recording when sharing a recording link.
|
||||
description: >
|
||||
Optional secret value that must be provided to access the recording via a shared link, enhancing security for shared recordings.
|
||||
schema:
|
||||
type: string
|
||||
|
||||
19
backend/openapi/components/parameters/recording-status.yaml
Normal file
19
backend/openapi/components/parameters/recording-status.yaml
Normal file
@ -0,0 +1,19 @@
|
||||
name: status
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
Filter recordings by their status.
|
||||
|
||||
You can provide multiple statuses as a comma-separated list (e.g., `status=ACTIVE,FAILED`).
|
||||
|
||||
> ⚠️ **Note:** Using this filter may impact performance for large datasets.
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- STARTING
|
||||
- ACTIVE
|
||||
- ENDING
|
||||
- COMPLETE
|
||||
- FAILED
|
||||
- ABORTED
|
||||
- LIMIT_REACHED
|
||||
@ -1,9 +1,9 @@
|
||||
name: fields
|
||||
in: query
|
||||
description: >
|
||||
The fields to retrieve from the room.
|
||||
Comma-separated list of fields to include in the response.
|
||||
Specifies which fields to include in the response for the room resource.
|
||||
Provide a comma-separated list of field names.
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
example: 'roomId,moderatorRoomUrl'
|
||||
example: 'roomId,moderatorRoomUrl'
|
||||
|
||||
@ -4,4 +4,4 @@ required: true
|
||||
description: The unique identifier of the room.
|
||||
schema:
|
||||
type: string
|
||||
example: 'room-123'
|
||||
example: 'room-123'
|
||||
|
||||
@ -1,7 +1,9 @@
|
||||
name: roomId
|
||||
in: query
|
||||
required: false
|
||||
description: The unique identifier of the room. Specify the room ID to filter recordings by their associated room.
|
||||
description: >
|
||||
The unique identifier for the room.
|
||||
Use this parameter to filter recordings and retrieve only those associated with the specified room ID.
|
||||
schema:
|
||||
type: string
|
||||
example: 'room-123'
|
||||
example: 'room-123'
|
||||
|
||||
@ -1,7 +1,9 @@
|
||||
name: roomIds
|
||||
in: query
|
||||
required: true
|
||||
description: A comma-separated list of room IDs to delete.
|
||||
description: >
|
||||
Comma-separated list of room IDs to delete.
|
||||
Each ID should correspond to an existing room.
|
||||
schema:
|
||||
type: string
|
||||
example: 'room-123,room-456'
|
||||
example: 'room-123,room-456'
|
||||
|
||||
@ -2,7 +2,6 @@ name: x-signature
|
||||
in: header
|
||||
description: >
|
||||
HMAC-SHA256 signature of the request body, created using your webhook secret.
|
||||
|
||||
Use this to verify the webhook came from OpenVidu Meet and wasn't tampered with.
|
||||
required: true
|
||||
schema:
|
||||
|
||||
@ -2,9 +2,7 @@ name: x-timestamp
|
||||
in: header
|
||||
description: >
|
||||
Unix timestamp (in seconds) when the webhook was sent.
|
||||
|
||||
Can be used to validate webhook age and prevent replay attacks.
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
example: '1697030400000'
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Room creation details
|
||||
description: Room creation options
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Recording details
|
||||
description: Room to record
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Room update details
|
||||
description: New room preferences
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Security preferences
|
||||
description: New security preferences
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Webhooks preferences
|
||||
description: New webhooks preferences
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Conflict — The recording is in `STARTING` state or already stopped
|
||||
description: Conflict — The recording is starting or already stopped
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Successfully disconnect the participant
|
||||
description: Successfully disconnected the participant
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
||||
@ -15,4 +15,4 @@ headers:
|
||||
schema:
|
||||
type: string
|
||||
format: uri
|
||||
example: https://your-api.com/meet/internal-api/v1/recordings/room-123--EG_XYZ--XX445
|
||||
example: https://your-api.com/internal-api/v1/recordings/room-123--EG_XYZ--XX445
|
||||
|
||||
@ -4,7 +4,7 @@ headers:
|
||||
description: The URL to retrieve the recording details
|
||||
schema:
|
||||
type: string
|
||||
example: 'https://openvidu.example.com/meet/api/v1/recordings/room-123--EG_XYZ--XX445'
|
||||
example: 'https://openvidu.example.com/api/v1/recordings/room-123--EG_XYZ--XX445'
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
||||
@ -2,7 +2,7 @@ description: Successfully logged in
|
||||
headers:
|
||||
Set-Cookie:
|
||||
$ref: '../../headers/set-cookie-access-token.yaml'
|
||||
Set-Cookie-Refresh:
|
||||
Set-Cookie*:
|
||||
$ref: '../../headers/set-cookie-refresh-token.yaml'
|
||||
content:
|
||||
application/json:
|
||||
|
||||
@ -1,13 +1,11 @@
|
||||
description: Successfully logged out
|
||||
headers:
|
||||
Set-Cookie:
|
||||
description: >
|
||||
Clears the access and refresh token cookie.
|
||||
schema:
|
||||
type: string
|
||||
example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict'
|
||||
Set-Cookie-Refresh:
|
||||
schema:
|
||||
type: string
|
||||
example: 'OvMeetRefreshToken=; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
|
||||
example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict'
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: PRO Feature Error
|
||||
description: PRO feature
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
||||
@ -36,14 +36,14 @@ content:
|
||||
- recordingId: 'room-123--EG_XYZ--XX447'
|
||||
error: 'Recording not found'
|
||||
- recordingId: 'room-123--EG_XYZ--XX448'
|
||||
error: 'Access denied for deletion'
|
||||
error: 'Recording in progress'
|
||||
|
||||
no_deletion_performed:
|
||||
summary: No recordings were deleted
|
||||
value:
|
||||
deleted: []
|
||||
notDeleted:
|
||||
- recordingId: 'room-123--EG_XYZ--XX445'
|
||||
error: 'Recording not found'
|
||||
- recordingId: 'room-123--EG_ZYX--XX446'
|
||||
- recordingId: 'room-123--EG_XYZ--XX447'
|
||||
error: 'Recording not found'
|
||||
- recordingId: 'room-123--EG_ZYX--XX448'
|
||||
error: 'Recording in progress'
|
||||
|
||||
@ -15,7 +15,9 @@ content:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: List of rooms that were marked for deletion but not actually deleted. The rooms will be deleted when all participants leave the room.
|
||||
description: >-
|
||||
List of rooms that were marked for deletion but not actually deleted.
|
||||
These rooms will be deleted when all participants leave.
|
||||
example:
|
||||
deleted:
|
||||
- 'room-123'
|
||||
|
||||
@ -9,4 +9,4 @@ headers:
|
||||
schema:
|
||||
type: string
|
||||
format: uri
|
||||
example: https://your-api.com/meet/api/v1/rooms/room-id-123
|
||||
example: https://your-api.com/api/v1/rooms/room-123
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Successfully retrieved the recording URL.
|
||||
description: Successfully retrieved the recording URL
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
@ -7,5 +7,5 @@ content:
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: URL to access the recording media.
|
||||
example: https://example.com/meet/api/v1/recordings/room-123--EG_XYZ--XX445/media?secret=abc123
|
||||
description: URL to access the recording.
|
||||
example: https://example.com/recording/room-123--EG_XYZ--XX445?secret=abc123
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Successfully retrieved the recording.
|
||||
description: Successfully retrieved the recording
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
||||
@ -18,8 +18,8 @@ content:
|
||||
enabled: false
|
||||
virtualBackgroundPreferences:
|
||||
enabled: true
|
||||
moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456'
|
||||
publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'
|
||||
moderatorURL: 'http://localhost:6080/room/room-123?secret=123456'
|
||||
publisherURL: 'http://localhost:6080/room/room-123?secret=654321'
|
||||
|
||||
fields=roomId:
|
||||
summary: Response with only the roomId
|
||||
@ -44,5 +44,5 @@ content:
|
||||
fields=moderatorURL,publisherURL:
|
||||
summary: Response containing only moderator and publisher URLs
|
||||
value:
|
||||
moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456'
|
||||
publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'
|
||||
moderatorURL: 'http://localhost:6080/room/room-123?secret=123456'
|
||||
publisherURL: 'http://localhost:6080/room/room-123?secret=654321'
|
||||
|
||||
@ -27,8 +27,8 @@ content:
|
||||
enabled: false
|
||||
virtualBackgroundPreferences:
|
||||
enabled: true
|
||||
moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456'
|
||||
publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'
|
||||
moderatorURL: 'http://localhost:6080/room/room-123?secret=123456'
|
||||
publisherURL: 'http://localhost:6080/room/room-123?secret=654321'
|
||||
- roomId: 'room-456'
|
||||
roomIdPrefix: 'room'
|
||||
creationDate: 1620001000000
|
||||
@ -40,8 +40,8 @@ content:
|
||||
enabled: true
|
||||
virtualBackgroundPreferences:
|
||||
enabled: false
|
||||
moderatorURL: 'http://localhost:6080/room/room-456/?secret=789012'
|
||||
publisherURL: 'http://localhost:6080/room/room-456/?secret=210987'
|
||||
moderatorURL: 'http://localhost:6080/room/room-456?secret=789012'
|
||||
publisherURL: 'http://localhost:6080/room/room-456?secret=210987'
|
||||
pagination:
|
||||
isTruncated: false
|
||||
maxItems: 10
|
||||
@ -90,10 +90,10 @@ content:
|
||||
summary: Response containing only moderator and publisher URLs
|
||||
value:
|
||||
rooms:
|
||||
- moderatorURL: 'http://localhost:6080/room/room-123/?secret=123456'
|
||||
publisherURL: 'http://localhost:6080/room/room-123/?secret=654321'
|
||||
- moderatorURL: 'http://localhost:6080/room/room-456/?secret=789012'
|
||||
publisherURL: 'http://localhost:6080/room/room-456/?secret=210987'
|
||||
- moderatorURL: 'http://localhost:6080/room/room-123?secret=123456'
|
||||
publisherURL: 'http://localhost:6080/room/room-123?secret=654321'
|
||||
- moderatorURL: 'http://localhost:6080/room/room-456?secret=789012'
|
||||
publisherURL: 'http://localhost:6080/room/room-456?secret=210987'
|
||||
pagination:
|
||||
isTruncated: false
|
||||
maxItems: 10
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
description: >
|
||||
All specified rooms were marked error for deletion (due to active participants)
|
||||
All specified rooms were marked for deletion (due to active participants)
|
||||
and will be removed once all participants leave.
|
||||
content:
|
||||
application/json:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
description: Unprocessable Entity — Invalid request body
|
||||
description: Unprocessable Entity — Invalid request
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
description: >
|
||||
Webhook received and processed successfully.
|
||||
description: |
|
||||
Webhook received and processed successfully.
|
||||
|
||||
Important: Webhook endpoints must return HTTP 200 OK promptly to acknowledge receipt.
|
||||
Any processing should be done asynchronously after responding.
|
||||
|
||||
Non-200 responses or timeouts will trigger retries according to the webhook delivery policy.
|
||||
> **Important:** Webhook endpoints must return HTTP 200 OK promptly to acknowledge receipt.
|
||||
> Any processing should be done asynchronously after responding.
|
||||
>
|
||||
> Non-200 responses or timeouts will trigger retries according to the webhook delivery policy.
|
||||
|
||||
@ -23,8 +23,7 @@ properties:
|
||||
room:
|
||||
type: string
|
||||
description: >
|
||||
The ID of the room associated with the participant.
|
||||
example: roomId
|
||||
Unique identifier of the room to which the participant is assigned.
|
||||
canPublish:
|
||||
type: boolean
|
||||
description: >
|
||||
@ -61,5 +60,5 @@ properties:
|
||||
canChangeVirtualBackground:
|
||||
type: boolean
|
||||
description: >
|
||||
Indicates whether the participant can change virtual background in the room.
|
||||
Indicates whether the participant can change their own virtual background.
|
||||
example: true
|
||||
|
||||
@ -16,7 +16,9 @@ AuthenticationPreferences:
|
||||
- single-user
|
||||
default: single-user
|
||||
example: single-user
|
||||
description: The authentication method to use.
|
||||
description: |
|
||||
Specifies the authentication method used to access the application.
|
||||
- `single-user`: Only one user account exists, which has administrative privileges and is used for all access.
|
||||
authModeToAccessRoom:
|
||||
type: string
|
||||
enum:
|
||||
@ -25,4 +27,8 @@ AuthenticationPreferences:
|
||||
- all_users
|
||||
default: none
|
||||
example: none
|
||||
description: The authentication mode to access a room.
|
||||
description: |
|
||||
Specifies who is required to authenticate before accessing a room:
|
||||
- `none`: No authentication required.
|
||||
- `moderators_only`: Only moderators need to authenticate.
|
||||
- `all_users`: All users must authenticate.
|
||||
|
||||
@ -8,5 +8,6 @@ properties:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
enum: ['admin', 'user']
|
||||
example: ['admin', 'user']
|
||||
description: A list of roles assigned to the authenticated user.
|
||||
|
||||
@ -6,5 +6,6 @@ properties:
|
||||
description: Indicates whether webhooks are enabled or disabled.
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
example: 'https://example.com/webhook'
|
||||
description: The URL to which webhooks will be sent. This is only mandatory if webhooks are enabled.
|
||||
|
||||
@ -3,13 +3,13 @@ properties:
|
||||
isTruncated:
|
||||
type: boolean
|
||||
description: >
|
||||
Indicates if there are more elements to retrieve.
|
||||
If true, use the `nextPageToken` to fetch the next set of elements.
|
||||
Indicates if there are more items to retrieve.
|
||||
If true, use the `nextPageToken` to fetch the next set of items.
|
||||
nextPageToken:
|
||||
type: [string, 'null']
|
||||
description: The token to retrieve the next page of elements.
|
||||
description: The token to retrieve the next page of items.
|
||||
maxItems:
|
||||
type: integer
|
||||
description: >
|
||||
Maximum number of elements returned in a single response page.
|
||||
Maximum number of items returned in a single response page.
|
||||
Corresponds to the `maxItems` query parameter in the request.
|
||||
|
||||
@ -3,15 +3,14 @@ properties:
|
||||
autoDeletionDate:
|
||||
type: [number, 'null']
|
||||
example: 1900000000000
|
||||
description: >
|
||||
The date and time when the room will be deleted (must be one hour in the future or more) represented in milliseconds since the Unix epoch.
|
||||
description: |
|
||||
The timestamp (in milliseconds since the Unix epoch) specifying when the room will be automatically deleted.
|
||||
This must be at least one hour in the future.
|
||||
|
||||
After this date, the room will be automatically deleted and no new participants can join.
|
||||
After this time, the room is closed to new participants and scheduled for deletion.
|
||||
It will be removed after the last participant leaves (graceful deletion).
|
||||
|
||||
If this value is set and the date has already passed, the room is marked for deletion but will only be removed after the last
|
||||
participant leaves ("graceful deletion").
|
||||
|
||||
If this value is not defined, the room will exist indefinitely until manually deleted.
|
||||
If not set, the room remains active until manually deleted.
|
||||
roomIdPrefix:
|
||||
type: string
|
||||
example: 'room'
|
||||
|
||||
@ -18,15 +18,14 @@ properties:
|
||||
autoDeletionDate:
|
||||
type: [number, 'null']
|
||||
example: 1900000000000
|
||||
description: >
|
||||
The date and time when the room will be deleted (must be one hour in the future or more) represented in milliseconds since the Unix epoch.
|
||||
description: |
|
||||
The timestamp (in milliseconds since the Unix epoch) specifying when the room will be automatically deleted.
|
||||
This must be at least one hour in the future.
|
||||
|
||||
After this date, the room will be automatically deleted and no new participants can join.
|
||||
After this time, the room is closed to new participants and scheduled for deletion.
|
||||
It will be removed after the last participant leaves (graceful deletion).
|
||||
|
||||
If this value is set and the date has already passed, the room is marked for deletion but will only be removed after the last
|
||||
participant leaves ("graceful deletion").
|
||||
|
||||
If this value is not defined, the room will exist indefinitely until manually deleted.
|
||||
If not set, the room remains active until manually deleted.
|
||||
preferences:
|
||||
$ref: meet-room-preferences.yaml#/MeetRoomPreferences
|
||||
description: The preferences for the room.
|
||||
@ -38,13 +37,13 @@ properties:
|
||||
# this limit, new participants will not be allowed to join.
|
||||
moderatorURL:
|
||||
type: string
|
||||
example: 'http://localhost:6080/room/room-123/?secret=123456'
|
||||
example: 'http://localhost:6080/room/room-123?secret=123456'
|
||||
description: >
|
||||
The URL for the moderator to join the room. The moderator has special permissions to manage the
|
||||
The URL for the moderator participants to join the room. The moderator role has special permissions to manage the
|
||||
room and participants.
|
||||
publisherURL:
|
||||
type: string
|
||||
example: 'http://localhost:6080/room/room-123/?secret=654321'
|
||||
example: 'http://localhost:6080/room/room-123?secret=654321'
|
||||
description: >
|
||||
The URL for the publisher to join the room. The publisher has permissions to publish audio and
|
||||
The URL for the publisher participants to join the room. The publisher role has permissions to publish audio and
|
||||
video streams to the room.
|
||||
|
||||
@ -1,17 +1,17 @@
|
||||
type: object
|
||||
required:
|
||||
- creationDate
|
||||
- event
|
||||
- data
|
||||
- creationDate
|
||||
- event
|
||||
- data
|
||||
properties:
|
||||
creationDate:
|
||||
type: number
|
||||
description: The date when the event was created (milliseconds since the Unix epoch).
|
||||
example: 1620000000000
|
||||
event:
|
||||
type: string
|
||||
description: Event type identifier.
|
||||
example: webhookEvent
|
||||
data:
|
||||
type: object
|
||||
description: The data associated with the event.
|
||||
creationDate:
|
||||
type: number
|
||||
description: The date when the event was created (milliseconds since the Unix epoch).
|
||||
example: 1620000000000
|
||||
event:
|
||||
type: string
|
||||
description: Event type identifier.
|
||||
example: webhookEvent
|
||||
data:
|
||||
type: object
|
||||
description: The data associated with the event.
|
||||
|
||||
@ -15,7 +15,7 @@ refreshTokenCookie:
|
||||
name: OvMeetRefreshToken
|
||||
in: cookie
|
||||
description: >
|
||||
The JWT token to refresh the access token when it expires. This token is used to obtain a new access token.
|
||||
The JWT token to refresh the access token when it expires..
|
||||
participantTokenCookie:
|
||||
type: apiKey
|
||||
name: OvMeetParticipantToken
|
||||
|
||||
@ -26,8 +26,6 @@ paths:
|
||||
components:
|
||||
securitySchemes:
|
||||
$ref: './components/security.yaml'
|
||||
# responses:
|
||||
# $ref: './components/responses.yaml'
|
||||
schemas:
|
||||
MeetRoom:
|
||||
$ref: components/schemas/meet-room.yaml
|
||||
|
||||
@ -27,28 +27,11 @@
|
||||
- Internal API - Authentication
|
||||
responses:
|
||||
'200':
|
||||
description: Successfully logged out
|
||||
headers:
|
||||
Set-Cookie:
|
||||
schema:
|
||||
type: string
|
||||
example: 'OvMeetAccessToken=; Path=/; HttpOnly; SameSite=Strict'
|
||||
Set-Cookie-Refresh:
|
||||
schema:
|
||||
type: string
|
||||
example: 'OvMeetRefreshToken=; Path=/meet/internal-api/v1/auth; HttpOnly; SameSite=Strict'
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
message:
|
||||
type: string
|
||||
example: 'Logout successful'
|
||||
$ref: '../../components/responses/internal/success-user-logout.yaml'
|
||||
/auth/refresh:
|
||||
post:
|
||||
operationId: refreshAccessToken
|
||||
summary: Refresh the access token
|
||||
summary: Refresh access token
|
||||
description: >
|
||||
Refreshes the access token using the refresh token.
|
||||
The new access token is returned in a cookie.
|
||||
@ -68,10 +51,11 @@
|
||||
post:
|
||||
operationId: createApiKey
|
||||
summary: Create a new API key
|
||||
description: >
|
||||
Creates a new API key. Only one API key can be created in the system.
|
||||
If an API key already exists, it will be replaced with the new one.
|
||||
The API key is returned in the response.
|
||||
description: |
|
||||
Creates a new API key, returning it in the response.
|
||||
|
||||
> **Note:** Only one API key can be created in the system.
|
||||
> If an API key already exists, it will be replaced with the new one.
|
||||
tags:
|
||||
- Internal API - Authentication
|
||||
security:
|
||||
@ -84,8 +68,11 @@
|
||||
get:
|
||||
operationId: getApiKeys
|
||||
summary: Get API keys
|
||||
description: >
|
||||
description: |
|
||||
Retrieves the existing API keys.
|
||||
|
||||
> **Note:** Only one API key can exist in the system.
|
||||
> If no API key exists, an empty array will be returned.
|
||||
tags:
|
||||
- Internal API - Authentication
|
||||
security:
|
||||
@ -106,9 +93,6 @@
|
||||
- accessTokenCookie: []
|
||||
responses:
|
||||
'204':
|
||||
description: Successfully deleted the API key
|
||||
description: Successfully deleted the API key. No content is returned.
|
||||
'500':
|
||||
$ref: '../../components/responses/internal-server-error.yaml'
|
||||
|
||||
|
||||
|
||||
|
||||
@ -45,7 +45,7 @@
|
||||
operationId: testWebhookUrl
|
||||
summary: Test webhook URL
|
||||
description: >
|
||||
Tests the provided webhook URL to ensure it is reachable and valid.
|
||||
Tests the provided webhook URL to ensure it is valid and reachable.
|
||||
tags:
|
||||
- Internal API - Global Preferences
|
||||
requestBody:
|
||||
|
||||
@ -2,8 +2,8 @@
|
||||
delete:
|
||||
operationId: endMeeting
|
||||
summary: End a meeting
|
||||
description: >
|
||||
Ends a meeting in an OpenVidu Meet room. This will stop all recordings and disconnect all participants.
|
||||
description: |
|
||||
Ends the current meeting in an OpenVidu Meet room. This will stop all recordings and disconnect all participants.
|
||||
|
||||
This endpoint is idempotent. If the meeting is already ended, it will return a success response without any action.
|
||||
tags:
|
||||
@ -29,9 +29,9 @@
|
||||
/meetings/{roomId}/participants/{participantName}:
|
||||
delete:
|
||||
operationId: disconnectParticipant
|
||||
summary: Delete a participant from a meeting
|
||||
summary: Kick a participant from a meeting
|
||||
description: >
|
||||
Deletes a participant from an OpenVidu Meet room. This will disconnect the participant from the meeting.
|
||||
Kicks a participant from the current meeting in an OpenVidu Meet room.
|
||||
tags:
|
||||
- Internal API - Meetings
|
||||
security:
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
/participants/token:
|
||||
post:
|
||||
operationId: generateParticipantToken
|
||||
summary: Generate a token for a participant
|
||||
summary: Generate token for participant
|
||||
description: >
|
||||
Generates a token for a participant to join an OpenVidu Meet room.
|
||||
tags:
|
||||
@ -30,7 +30,7 @@
|
||||
/participants/token/refresh:
|
||||
post:
|
||||
operationId: refreshParticipantToken
|
||||
summary: Refresh a token for a participant
|
||||
summary: Refresh token for participant
|
||||
description: >
|
||||
Refresh a token for a participant in an OpenVidu Meet room.
|
||||
tags:
|
||||
|
||||
@ -35,9 +35,10 @@
|
||||
post:
|
||||
operationId: stopRecording
|
||||
summary: Stop a recording
|
||||
description: >
|
||||
description: |
|
||||
Stops a recording with the specified recording ID.
|
||||
The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned.
|
||||
|
||||
> **Note:** The recording must be in an `ACTIVE` state; otherwise, a 409 error is returned.
|
||||
tags:
|
||||
- Internal API - Recordings
|
||||
security:
|
||||
|
||||
@ -106,9 +106,10 @@
|
||||
get:
|
||||
operationId: getRoomRoleAndPermissions
|
||||
summary: Get room role and permissions
|
||||
description: >
|
||||
description: |
|
||||
Retrieves the role and associated permissions that a participant will have in a specified OpenVidu Meet room
|
||||
when using the URL thant contains the given secret value.
|
||||
|
||||
This endpoint is useful for checking the participant's role and permissions before joining the room.
|
||||
tags:
|
||||
- Internal API - Rooms
|
||||
|
||||
@ -2,12 +2,12 @@
|
||||
get:
|
||||
operationId: getRecordings
|
||||
summary: Get all recordings
|
||||
description: >
|
||||
description: |
|
||||
Retrieves a paginated list of all recordings available in the system.
|
||||
You can apply filters to narrow down the results based on specific criteria.
|
||||
|
||||
> **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
|
||||
the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned.
|
||||
> the `roomId` filter will be ignored and only recordings associated with the room included in the token will be returned.
|
||||
tags:
|
||||
- OpenVidu Meet - Recordings
|
||||
security:
|
||||
@ -15,27 +15,7 @@
|
||||
- accessTokenCookie: []
|
||||
- recordingTokenCookie: []
|
||||
parameters:
|
||||
# - name: status
|
||||
# in: query
|
||||
# required: false
|
||||
# description: |
|
||||
# Filter recordings by their status.
|
||||
|
||||
# Possible values:
|
||||
# - `STARTING`
|
||||
# - `ACTIVE`
|
||||
# - `ENDING`
|
||||
# - `COMPLETE`
|
||||
# - `FAILED`
|
||||
# - `ABORTED`
|
||||
# - `LIMITED_REACHED`
|
||||
|
||||
# You can provide multiple statuses as a comma-separated list (e.g., `status=ACTIVE,FAILED`).
|
||||
# If not specified, recordings with any status will be returned.
|
||||
|
||||
# > ⚠️ **Note:** Using this filter may impact performance for large datasets.
|
||||
# schema:
|
||||
# type: string
|
||||
# - $ref: '../components/parameters/recording-status.yaml'
|
||||
- $ref: '../components/parameters/recording-fields.yaml'
|
||||
- $ref: '../components/parameters/room-id-query.yaml'
|
||||
- $ref: '../components/parameters/max-items.yaml'
|
||||
@ -55,12 +35,12 @@
|
||||
delete:
|
||||
operationId: bulkDeleteRecordings
|
||||
summary: Bulk delete recordings
|
||||
description: >
|
||||
description: |
|
||||
Deletes multiple recordings at once with the specified recording IDs.
|
||||
|
||||
> **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
|
||||
all specified recordings must belong to the same room included in the token.
|
||||
If a recording does not belong to that room, it will not be deleted.
|
||||
> all specified recordings must belong to the same room included in the token.
|
||||
> If a recording does not belong to that room, it will not be deleted.
|
||||
tags:
|
||||
- OpenVidu Meet - Recordings
|
||||
security:
|
||||
@ -89,13 +69,13 @@
|
||||
get:
|
||||
operationId: downloadRecordings
|
||||
summary: Download recordings
|
||||
description: >
|
||||
description: |
|
||||
Downloads multiple recordings as a ZIP file with the specified recording IDs.
|
||||
The ZIP file will contain all recordings in MP4 format.
|
||||
|
||||
> **Note:** If this endpoint is called using the `recordingTokenCookie` authentication method,
|
||||
all specified recordings must belong to the same room included in the token.
|
||||
If a recording does not belong to that room, it will not be included in the ZIP file.
|
||||
> all specified recordings must belong to the same room included in the token.
|
||||
> If a recording does not belong to that room, it will not be included in the ZIP file.
|
||||
tags:
|
||||
- OpenVidu Meet - Recordings
|
||||
security:
|
||||
@ -145,6 +125,7 @@
|
||||
- recordingTokenCookie: []
|
||||
parameters:
|
||||
- $ref: '../components/parameters/recording-id.yaml'
|
||||
- $ref: '../components/parameters/recording-secret.yaml'
|
||||
responses:
|
||||
'200':
|
||||
$ref: '../components/responses/success-get-recording.yaml'
|
||||
@ -163,9 +144,11 @@
|
||||
delete:
|
||||
operationId: deleteRecording
|
||||
summary: Delete a recording
|
||||
description: >
|
||||
Deletes a recording with the specified recording.
|
||||
The recording will only be deleted if it exists and is not in progress (i.e., not in a state such as `ACTIVE`, `STARTING`, or `ENDING`).
|
||||
description: |
|
||||
Deletes a recording with the specified recording ID.
|
||||
|
||||
> ⚠️ **Note:** The recording will only be deleted if it exists and is not in progress
|
||||
> (i.e., not in a state such as `ACTIVE`, `STARTING`, or `ENDING`).
|
||||
tags:
|
||||
- OpenVidu Meet - Recordings
|
||||
security:
|
||||
@ -193,9 +176,10 @@
|
||||
get:
|
||||
operationId: getRecordingMedia
|
||||
summary: Get recording media
|
||||
description: >
|
||||
description: |
|
||||
Retrieves the media of a recording with the specified recording ID.
|
||||
The media is returned in a binary format suitable for video playback.
|
||||
|
||||
This endpoint supports range requests, allowing partial content retrieval
|
||||
for video playback without downloading the entire file.
|
||||
tags:
|
||||
@ -210,7 +194,7 @@
|
||||
- $ref: '../components/parameters/recording-range.yaml'
|
||||
responses:
|
||||
'200':
|
||||
description: Successfully streaming the full recording
|
||||
description: Successfully retrieved the full recording media
|
||||
headers:
|
||||
Accept-Ranges:
|
||||
$ref: '../components/headers/accept-ranges.yaml'
|
||||
@ -224,7 +208,7 @@
|
||||
type: string
|
||||
format: binary
|
||||
'206':
|
||||
description: Partial content streaming based on byte range
|
||||
description: Successfully retrieved a partial range of the recording media
|
||||
headers:
|
||||
Accept-Ranges:
|
||||
$ref: '../components/headers/accept-ranges.yaml'
|
||||
@ -256,8 +240,8 @@
|
||||
schema:
|
||||
$ref: '../components/schemas/error.yaml'
|
||||
example:
|
||||
code: 416
|
||||
message: 'Requested range not satisfiable'
|
||||
error: Recording Error
|
||||
message: 'Recording "room-123--EG_XYZ--XX445" range not satisfiable. File size: 123456789'
|
||||
'422':
|
||||
$ref: '../components/responses/validation-error.yaml'
|
||||
'500':
|
||||
@ -266,9 +250,10 @@
|
||||
get:
|
||||
operationId: getRecordingUrl
|
||||
summary: Get recording URL
|
||||
description: >
|
||||
description: |
|
||||
Retrieves the URL of a recording with the specified recording ID.
|
||||
This URL is intended to be shared with people who do not have direct access to the recording.
|
||||
|
||||
It can be configured to be accessible by anyone (public access) or restricted to authenticated users only,
|
||||
depending on the `privateAccess` query parameter.
|
||||
tags:
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
operationId: createRoom
|
||||
summary: Create a room
|
||||
description: >
|
||||
Creates a new OpenVidu Meet room with the specified expiration date.
|
||||
Creates a new OpenVidu Meet room.
|
||||
The room will be available for participants to join using the generated URLs.
|
||||
tags:
|
||||
- OpenVidu Meet - Room
|
||||
@ -29,6 +29,7 @@
|
||||
summary: Get all rooms
|
||||
description: >
|
||||
Retrieves a paginated list of all rooms available in the system.
|
||||
You can apply filters to narrow down the results based on specific criteria.
|
||||
tags:
|
||||
- OpenVidu Meet - Room
|
||||
security:
|
||||
@ -53,7 +54,7 @@
|
||||
delete:
|
||||
operationId: bulkDeleteRooms
|
||||
summary: Bulk delete rooms
|
||||
description: >
|
||||
description: |
|
||||
Delete multiple OpenVidu Meet rooms at once with the specified room IDs.
|
||||
|
||||
If a room has active participants, it will be marked for deletion
|
||||
@ -120,7 +121,7 @@
|
||||
delete:
|
||||
operationId: deleteRoom
|
||||
summary: Delete a room
|
||||
description: >
|
||||
description: |
|
||||
Deletes an OpenVidu Meet room with the specified room ID.
|
||||
|
||||
If the room has active participants, it will be marked for deletion
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
recordingStarted:
|
||||
post:
|
||||
summary: Recording started
|
||||
description: >
|
||||
description: |
|
||||
This webhook is triggered when a recording starts.
|
||||
|
||||
> The recording can be in the `STARTING` status for a few seconds before it becomes `ACTIVE`.
|
||||
@ -31,7 +31,7 @@ recordingStarted:
|
||||
- properties:
|
||||
status:
|
||||
type: string
|
||||
enum: [STARTING]
|
||||
enum: [STARTING, ACTIVE]
|
||||
description: The status of the recording.
|
||||
example: STARTING
|
||||
responses:
|
||||
@ -41,7 +41,7 @@ recordingStarted:
|
||||
recordingUpdated:
|
||||
post:
|
||||
summary: Recording updated
|
||||
description: >
|
||||
description: |
|
||||
This webhook is triggered when a recording update occurs.
|
||||
|
||||
> This update can be due to a change in the recording status (e.g., from `STARTING` to `ACTIVE`).
|
||||
@ -81,10 +81,11 @@ recordingUpdated:
|
||||
recordingEnded:
|
||||
post:
|
||||
summary: Recording ended
|
||||
description: >
|
||||
description: |
|
||||
This webhook is triggered when a recording ends.
|
||||
|
||||
> The recording can end due to various reasons, such as the user stopping the recording or the recording reaching its maximum duration.
|
||||
> The recording can end due to various reasons, such as the user stopping the recording
|
||||
> or the recording reaching its maximum duration.
|
||||
operationId: recordingEndedWebhook
|
||||
parameters:
|
||||
- $ref: ../components/parameters/x-timestamp.yaml
|
||||
@ -112,7 +113,7 @@ recordingEnded:
|
||||
- properties:
|
||||
status:
|
||||
type: string
|
||||
enum: [COMPLETE, FAILED, ABORTED, LIMITED_REACHED]
|
||||
enum: [COMPLETE, FAILED, ABORTED, LIMIT_REACHED]
|
||||
description: The status of the recording.
|
||||
example: COMPLETE
|
||||
endDate:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user