neoris/openvidu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backend: API paths and parameters from 'roomName' to 'roomId' for consistency

Browse Source
This commit is contained in:
Carlos Santos 2025-04-02 09:54:56 +02:00
parent c94f262240
commit 1a4ecf873d
2 changed files with 161 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

342
backend/openapi/openvidu-meet-api.yaml
View File

@ -25,7 +25,7 @@ paths:
/rooms: /rooms:
post: post:
operationId: createRoom operationId: createRoom
summary: Create a new OpenVidu Meet room summary: Create a room
description: > description: >
Creates a new OpenVidu Meet room with the specified expiration date. Creates a new OpenVidu Meet room with the specified expiration date.
The room will be available for participants to join using the generated URLs. The room will be available for participants to join using the generated URLs.
@ -35,17 +35,17 @@ paths:
- apiKeyInHeader: [] - apiKeyInHeader: []
- accessTokenCookie: [] - accessTokenCookie: []
requestBody: requestBody:
description: Room configuration options description: Room creation details
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/OpenViduMeetRoomOptions' $ref: '#/components/schemas/MeetRoomOptions'
examples: examples:
default: default:
value: value:
expirationDate: 1620000000000 expirationDate: 1620000000000
roomNamePrefix: 'OpenVidu' roomIdPrefix: 'room'
maxParticipants: 10 # maxParticipants: 10
preferences: preferences:
chatPreferences: chatPreferences:
enabled: true enabled: true
@ -53,26 +53,13 @@ paths:
enabled: true enabled: true
virtualBackgroundPreferences: virtualBackgroundPreferences:
enabled: true enabled: true
withNestedAttributes:
summary: Room creation with nested preferences
value:
expirationDate: 1620000000000
roomNamePrefix: 'OpenVidu'
maxParticipants: 15
preferences:
chatPreferences:
enabled: true
recordingPreferences:
enabled: false
virtualBackgroundPreferences:
enabled: true
responses: responses:
'200': '200':
description: Successfully generated the OpenVidu Meet room description: Successfully created the OpenVidu Meet room
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/OpenViduMeetRoom' $ref: '#/components/schemas/MeetRoom'
'401': '401':
description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication
content: content:
@ -119,16 +106,8 @@ paths:
details: details:
- field: 'expirationDate' - field: 'expirationDate'
message: 'Expected number, received string' message: 'Expected number, received string'
- field: 'roomNamePrefix' - field: 'roomIdPrefix'
message: 'Expected string, received number' message: 'Expected string, received number'
'415':
description: 'Unsupported Media Type'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: 'Unsupported Media Type'
'500': '500':
description: Internal server error description: Internal server error
content: content:
@ -139,39 +118,28 @@ paths:
message: 'Internal server error' message: 'Internal server error'
get: get:
operationId: getRooms operationId: getRooms
summary: Get a list of OpenVidu Meet rooms summary: Get all rooms
description: > description: >
Retrieves a list of OpenVidu Meet rooms that are currently active. Retrieves a paginated list of all rooms available in the system.
You can specify a comma-separated list of fields (using the "fields" query parameter) to include only
those properties in the response (e.g. roomName, preferences).
tags: tags:
- OpenVidu Meet - Room - OpenVidu Meet - Room
security: security:
- apiKeyInHeader: [] - apiKeyInHeader: []
- accessTokenCookie: [] - accessTokenCookie: []
parameters: parameters:
- name: fields - name: maxItems
in: query in: query
required: false required: false
description: | description: The number of rooms per page (default is 10). Maximum is 100.
Comma-separated list of fields to include in the response.
For example: "roomName,preferences". Only allowed fields will be returned.
schema:
type: string
- name: page
in: query
required: false
description: The page number for pagination (default is 1).
schema:
type: integer
default: 1
- name: limit
in: query
required: false
description: The number of rooms per page (default is 10).
schema: schema:
type: integer type: integer
default: 10 default: 10
- name: nextPageToken
in: query
required: false
description: The token to retrieve the next page of rooms.
schema:
type: string
responses: responses:
'200': '200':
description: Successfully retrieved the list of OpenVidu Meet rooms description: Successfully retrieved the list of OpenVidu Meet rooms
@ -183,19 +151,16 @@ paths:
rooms: rooms:
type: array type: array
items: items:
$ref: '#/components/schemas/OpenViduMeetRoom' $ref: '#/components/schemas/MeetRoom'
pagination: pagination:
type: object type: object
properties: properties:
totalItems: isTruncated:
type: integer type: boolean
description: Total number of rooms. description: Indicates if there are more rooms to retrieve.
totalPages: nextPageToken:
type: integer type: string
description: Total number of pages. description: The token to retrieve the next page of rooms.
currentPage:
type: integer
description: Current page number.
'401': '401':
description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication
@ -222,14 +187,12 @@ paths:
example: example:
code: 500 code: 500
message: 'Internal server error' message: 'Internal server error'
/rooms/{roomName}: /rooms/{roomId}:
get: get:
operationId: getRoom operationId: getRoom
summary: Get details of an OpenVidu Meet room summary: Get a room
description: > description: >
Retrieves the details of an OpenVidu Meet room with the specified room name. Retrieves the details of an OpenVidu Meet room with the specified room ID.
Additionally, you can specify a comma-separated list of fields (using the "fields" query parameter)
to include only those properties in the response (e.g. roomName, preferences).
tags: tags:
- OpenVidu Meet - Room - OpenVidu Meet - Room
security: security:
@ -237,27 +200,20 @@ paths:
- accessTokenCookie: [] - accessTokenCookie: []
- participantTokenCookie: [] - participantTokenCookie: []
parameters: parameters:
- name: roomName - name: roomId
in: path in: path
required: true required: true
description: The name of the room to retrieve description: The unique identifier of the room to retrieve
schema:
type: string
- name: fields
in: query
required: false
description: |
Comma-separated list of fields to include in the response.
For example: "roomName,preferences". Only allowed fields will be returned.
schema: schema:
type: string type: string
example: 'room-123'
responses: responses:
'200': '200':
description: Successfully retrieved the OpenVidu Meet room description: Successfully retrieved the room
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/OpenViduMeetRoom' $ref: '#/components/schemas/MeetRoom'
'401': '401':
description: Unauthorized — The API key is missing or invalid, or the access/participant token is missing or invalid when using cookie-based authentication description: Unauthorized — The API key is missing or invalid, or the access/participant token is missing or invalid when using cookie-based authentication
content: content:
@ -294,27 +250,28 @@ paths:
message: 'Internal server error' message: 'Internal server error'
put: put:
operationId: updateRoom operationId: updateRoom
summary: Update an OpenVidu Meet room summary: Update a room
description: > description: >
Updates the preferences of an OpenVidu Meet room with the specified room name. Updates the preferences of an OpenVidu Meet room with the specified room ID.
tags: tags:
- OpenVidu Meet - Room - OpenVidu Meet - Room
security: security:
- apiKeyInHeader: [] - apiKeyInHeader: []
- accessTokenCookie: [] - accessTokenCookie: []
parameters: parameters:
- name: roomName - name: roomId
in: path in: path
required: true required: true
description: The name of the room to update description: The unique identifier of the room to update
schema: schema:
type: string type: string
example: 'room-123'
requestBody: requestBody:
description: Room preferences to update description: Room update details
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/RoomPreferences' $ref: '#/components/schemas/MeetRoomPreferences'
examples: examples:
default: default:
value: value:
@ -331,7 +288,7 @@ paths:
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/OpenViduMeetRoom' $ref: '#/components/schemas/MeetRoom'
'401': '401':
description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication description: Unauthorized — The API key is missing or invalid, or the access token is missing or invalid when using cookie-based authentication
content: content:
@ -381,23 +338,35 @@ paths:
message: message:
type: string type: string
example: 'Expected boolean, received 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: delete:
operationId: deleteRoom operationId: deleteRoom
summary: Delete an OpenVidu Meet room summary: Delete a room
description: > description: >
Deletes an OpenVidu Meet room with the specified room name. 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: tags:
- OpenVidu Meet - Room - OpenVidu Meet - Room
security: security:
- apiKeyInHeader: [] - apiKeyInHeader: []
- accessTokenCookie: [] - accessTokenCookie: []
parameters: parameters:
- name: roomName - name: roomId
in: path in: path
required: true required: true
description: The name of the room to delete description: The unique identifier of the room to delete
schema: schema:
type: string type: string
example: 'room-123'
responses: responses:
'204': '204':
description: Successfully deleted the OpenVidu Meet room description: Successfully deleted the OpenVidu Meet room
@ -965,86 +934,19 @@ components:
description: > description: >
The JWT token to authenticate the participant when entering the room. The JWT token to authenticate the participant when entering the room.
schemas: schemas:
OpenViduMeetRoomOptions: MeetRoom:
type: object type: object
required:
- expirationDate
properties: properties:
expirationDate: roomId:
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.
roomNamePrefix:
type: string type: string
example: 'OpenVidu' example: 'room-123'
description: > description: >
A prefix to be used for the room name. The room name will be generated by appending a random The unique identifier of the room. This ID is generated when the room is created.
alphanumeric string to this prefix. roomIdPrefix:
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/RoomPreferences'
description: >
The preferences for the room.
RoomPreferences:
type: object
properties:
chatPreferences:
$ref: '#/components/schemas/ChatPreferences'
description: >
Preferences for the chat feature in the room.
recordingPreferences:
$ref: '#/components/schemas/RecordingPreferences'
description: >
Preferences for recording the room.
virtualBackgroundPreferences:
$ref: '#/components/schemas/VirtualBackgroundPreferences'
description: >
Preferences for virtual background in the room.
ChatPreferences:
type: object
properties:
enabled:
type: boolean
default: true
example: true
description: >
If true, the room will be allowed to send and receive chat messages.
RecordingPreferences:
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.
VirtualBackgroundPreferences:
type: object
properties:
enabled:
type: boolean
default: true
example: true
description: >
If true, the room will be allowed to use virtual background.
OpenViduMeetRoom:
type: object
properties:
roomName:
type: string type: string
example: 'OpenVidu-123456' example: 'room'
description: > description: >
The name of the room. This name is generated by appending a random alphanumeric string to the The prefix used for the room ID. This prefix is used to generate the room ID.
room name prefix specified in the request.
creationDate: creationDate:
type: number type: number
example: 1620000000000 example: 1620000000000
@ -1056,40 +958,99 @@ components:
description: > description: >
The expiration date of the room in milliseconds since the Unix epoch. 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. After this date, the room will be closed and no new participants will be allowed to join.
roomNamePrefix:
type: string
example: 'OpenVidu'
description: >
The prefix used for the room name. The room name is generated by appending a random alphanumeric
string to this prefix.
preferences: preferences:
$ref: '#/components/schemas/RoomPreferences' $ref: '#/components/schemas/MeetRoomPreferences'
description: > description: >
The preferences for the room. The preferences for the room.
maxParticipants: # maxParticipants:
type: integer # type: integer
example: 10 # example: 10
description: > # description: >
The maximum number of participants allowed in the room. If the number of participants exceeds # 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. # this limit, new participants will not be allowed to join.
moderatorURL: moderatorURL:
type: string type: string
example: 'http://localhost:6080/meet/OpenVidu-123456/?secret=tok_123456' example: 'http://localhost:6080/room/room-123/?secret=tok_123456'
description: > description: >
The URL for the moderator to join the room. The moderator has special permissions to manage the The URL for the moderator to join the room. The moderator has special permissions to manage the
room and participants. room and participants.
publisherURL: publisherURL:
type: string type: string
example: 'http://localhost:6080/meet/OpenVidu-123456/?secret=tok_123456' example: 'http://localhost:6080/room/room-123/?secret=tok_123456'
description: > description: >
The URL for the publisher to join the room. The publisher has permissions to publish audio and The URL for the publisher to join the room. The publisher has permissions to publish audio and
video streams to the room. video streams to the room.
viewerURL:
type: string MeetRoomOptions:
example: 'http://localhost:6080/meet/OpenVidu-123456/?secret=tok_123456' type: object
required:
- expirationDate
properties:
expirationDate:
type: number
example: 1620000000000
description: > description: >
The URL for the viewer to join the room. The viewer has read-only permissions to watch the room The expiration date of the room in milliseconds since the Unix epoch.
and participants. 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.
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: MeetRecordingBase:
type: object type: object
properties: properties:
@ -1121,13 +1082,16 @@ components:
- LIMITED_REACHED - LIMITED_REACHED
filename: filename:
type: string type: string
example: 'room-123--XX445.mp4' example: 'http://localhost:6080/meet/OpenVidu-123456/?secret=tok_123456'
description: The name of the recording file. description: >
startDate: The URL for the publisher to join the room. The publisher has permissions to publish audio and
type: number video streams to the room.
example: 1620000000000 viewerURL:
description: The date when the recording was started (milliseconds since the Unix epoch). 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.
MeetRecording: MeetRecording:
allOf: allOf:
- $ref: '#/components/schemas/MeetRecordingBase' - $ref: '#/components/schemas/MeetRecordingBase'

16
backend/openapi/openvidu-meet-internal-api.yaml
View File

@ -223,7 +223,7 @@ paths:
$ref: '#/components/schemas/Error' $ref: '#/components/schemas/Error'
example: example:
message: 'Unauthorized' message: 'Unauthorized'
/rooms/{roomName}/participant-role: /rooms/{roomId}/participant-role:
get: get:
operationId: getParticipantRole operationId: getParticipantRole
summary: Get participant role in a room summary: Get participant role in a room
@ -235,7 +235,7 @@ paths:
security: security:
- accessTokenCookie: [] - accessTokenCookie: []
parameters: parameters:
- name: roomName - name: roomId
in: path in: path
required: true required: true
description: The name of the room to check the participant's role description: The name of the room to check the participant's role
@ -587,10 +587,10 @@ paths:
description: The name of the participant to delete description: The name of the participant to delete
schema: schema:
type: string type: string
- name: roomName - name: roomId
in: query in: query
required: true required: true
description: The name of the room from which to delete the participant description: The ID of the room where the participant is connected
schema: schema:
type: string type: string
responses: responses:
@ -726,15 +726,15 @@ components:
TokenOptions: TokenOptions:
type: object type: object
required: required:
- roomName - roomId
- participantName - participantName
- secret - secret
properties: properties:
roomName: roomId:
type: string type: string
example: 'OpenVidu-123456' example: 'room-123'
description: > description: >
The name of the room to join. The ID of the room where the participant will join.
participantName: participantName:
type: string type: string
example: 'Alice' example: 'Alice'