From 0ecc25bc74eba9a91763573594b6f68e53010ad7 Mon Sep 17 00:00:00 2001 From: lebaudantoine Date: Sat, 30 May 2026 14:52:29 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D(doc)=20update=20external=20API=20d?= =?UTF-8?q?ocs=20for=20room=20configuration=20support?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the changes introduced in #128333, which allows passing configuration to the external API when creating a room. Warning: this documentation was generated in a rush using an LLM and may contain minor errors. Plan to factorize these YAML files into a common and shared structure. --- docs/openapi.yaml | 78 +++++++++++++++++---- docs/resource_server.yaml | 139 +++++++++++++++++++------------------- 2 files changed, 135 insertions(+), 82 deletions(-) diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 018bee5e..ab24487e 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -185,6 +185,7 @@ paths: pin_code: "123456" phone_number: "+1-555-0100" default_country: "US" + configuration: {} '401': $ref: '#/components/responses/UnauthorizedError' '403': @@ -198,10 +199,6 @@ paths: description: | Creates a new room with secure defaults for external API usage. - **Restrictions:** - - Rooms are always created with `trusted` access (no public rooms via API) - - Room access_level can be updated from the webapp interface. - **Defaults:** - Delegated user is set as owner - Room slug auto-generated for uniqueness @@ -218,8 +215,17 @@ paths: $ref: '#/components/schemas/RoomCreate' examples: emptyBody: - summary: No parameters (default) - value: {} + summary: No parameters (use all defaults) + value: { } + withAccessLevel: + summary: Specify access level + value: + access_level: "trusted" + withConfiguration: + summary: Provide room configuration + value: + configuration: + everyone_can_mute: true responses: '201': description: Room created successfully @@ -269,6 +275,7 @@ paths: pin_code: "123456" phone_number: "+1-555-0100" default_country: "US" + configuration: {} '401': $ref: '#/components/responses/UnauthorizedError' '403': @@ -344,8 +351,56 @@ components: RoomCreate: type: object - description: Empty object - all room properties are auto-generated - properties: {} + description: | + Optional fields for room creation. All fields have secure defaults if omitted. + properties: + access_level: + $ref: '#/components/schemas/RoomAccessLevel' + configuration: + $ref: '#/components/schemas/RoomConfiguration' + + RoomConfiguration: + type: object + description: | + Optional room behaviour settings. Unknown fields are rejected. + All fields are optional and default to `null` (server-side defaults apply). + properties: + can_publish_sources: + type: array + nullable: true + description: | + Restricts which media tracks participants are allowed to publish. + If `null`, all sources are permitted. + items: + type: string + enum: + - camera + - microphone + - screen_share + - screen_share_audio + example: [ "camera", "microphone" ] + everyone_can_mute: + type: boolean + nullable: true + description: | + Whether any participant can mute others, or only the room owner/moderator. + If `null`, the server default applies. + example: true + additionalProperties: false + + RoomAccessLevel: + type: string + enum: + - public + - trusted + - restricted + description: | + Controls who can join the room without going through the lobby. + + - `public`: Anyone with the room link can join directly, no authentication required. + - `trusted`: Authenticated users join directly. Unauthenticated users wait in the lobby for approval. + - `restricted`: Only participants explicitly trusted by the owner bypass the lobby. Everyone else waits for approval regardless of authentication. + example: "trusted" Room: type: object @@ -362,10 +417,7 @@ components: description: URL-friendly room identifier (auto-generated) example: "aze-eere-zer" access_level: - type: string - readOnly: true - description: Room access level (always 'trusted' for API-created rooms) - example: "trusted" + $ref: '#/components/schemas/RoomAccessLevel' url: type: string format: uri @@ -393,6 +445,8 @@ components: type: string description: Default country code example: "US" + configuration: + $ref: '#/components/schemas/RoomConfiguration' OAuthError: type: object diff --git a/docs/resource_server.yaml b/docs/resource_server.yaml index 6184bb76..f6ab02a5 100644 --- a/docs/resource_server.yaml +++ b/docs/resource_server.yaml @@ -48,7 +48,7 @@ paths: summary: List rooms description: | Returns a list of rooms accessible to the authenticated user. - Only rooms where the delegated user has access will be returned. + Only rooms where the user has access will be returned. operationId: listRooms security: - BearerAuth: [rooms:list] @@ -108,6 +108,7 @@ paths: pin_code: "123456" phone_number: "+1-555-0100" default_country: "US" + configuration: { } '401': $ref: '#/components/responses/UnauthorizedError' '403': @@ -120,13 +121,9 @@ paths: summary: Create a room description: | Creates a new room with secure defaults for external API usage. - - **Restrictions:** - - Rooms are always created with `trusted` access (no public rooms via API) - - Room access_level can be updated from the webapp interface. - + **Defaults:** - - Delegated user is set as owner + - user is set as owner - Room slug auto-generated for uniqueness - Telephony PIN auto-generated when enabled - Creation tracked with application client_id for auditing @@ -141,8 +138,17 @@ paths: $ref: '#/components/schemas/RoomCreate' examples: emptyBody: - summary: No parameters (default) - value: {} + summary: No parameters (use all defaults) + value: { } + withAccessLevel: + summary: Specify access level + value: + access_level: "trusted" + withConfiguration: + summary: Provide room configuration + value: + configuration: + everyone_can_mute: true responses: '201': description: Room created successfully @@ -192,6 +198,7 @@ paths: pin_code: "123456" phone_number: "+1-555-0100" default_country: "US" + configuration: { } '401': $ref: '#/components/responses/UnauthorizedError' '403': @@ -210,65 +217,58 @@ components: Include in requests as: `Authorization: Bearer ` schemas: - TokenRequest: - type: object - required: - - client_id - - client_secret - - grant_type - - scope - properties: - client_id: - type: string - description: Application client identifier - example: "550e8400-e29b-41d4-a716-446655440000" - client_secret: - type: string - format: password - writeOnly: true - description: Application secret key - example: "1234567890abcdefghijklmnopqrstuvwxyz" - grant_type: - type: string - enum: - - client_credentials - description: OAuth2 grant type (must be 'client_credentials') - example: "client_credentials" - scope: - type: string - format: email - description: | - Email address of the user to delegate. - The application will act on behalf of this user. - Note: This parameter is named 'scope' to align with OAuth2 conventions, - but accepts an email address to identify the user. This design allows - for future extensibility. - example: "user@example.com" - - TokenResponse: - type: object - properties: - access_token: - type: string - description: JWT access token - example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtZWV0LWFwaSIsImF1ZCI6Im1lZXQtY2xpZW50cyIsImlhdCI6MTcwOTQ5MTIwMCwiZXhwIjoxNzA5NDk0ODAwLCJjbGllbnRfaWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJzY29wZSI6InJvb21zOmxpc3Qgcm9vbXM6cmV0cmlldmUgcm9vbXM6Y3JlYXRlIiwidXNlcl9pZCI6IjdiOGQ5YzQwLTNhMmItNGVkZi04NzFjLTJmM2Q0ZTVmNmE3YiIsImRlbGVnYXRlZCI6dHJ1ZX0.signature" - token_type: - type: string - description: Token type (always 'Bearer') - example: "Bearer" - expires_in: - type: integer - description: Token lifetime in seconds - example: 3600 - scope: - type: string - description: Space-separated list of granted permission scopes - example: "rooms:list rooms:retrieve rooms:create" - RoomCreate: type: object - description: Empty object - all room properties are auto-generated - properties: {} + description: | + Optional fields for room creation. All fields have secure defaults if omitted. + properties: + access_level: + $ref: '#/components/schemas/RoomAccessLevel' + configuration: + $ref: '#/components/schemas/RoomConfiguration' + + RoomConfiguration: + type: object + description: | + Optional room behaviour settings. Unknown fields are rejected. + All fields are optional and default to `null` (server-side defaults apply). + properties: + can_publish_sources: + type: array + nullable: true + description: | + Restricts which media tracks participants are allowed to publish. + If `null`, all sources are permitted. + items: + type: string + enum: + - camera + - microphone + - screen_share + - screen_share_audio + example: [ "camera", "microphone" ] + everyone_can_mute: + type: boolean + nullable: true + description: | + Whether any participant can mute others, or only the room owner/moderator. + If `null`, the server default applies. + example: true + additionalProperties: false + + RoomAccessLevel: + type: string + enum: + - public + - trusted + - restricted + description: | + Controls who can join the room without going through the lobby. + + - `public`: Anyone with the room link can join directly, no authentication required. + - `trusted`: Authenticated users join directly. Unauthenticated users wait in the lobby for approval. + - `restricted`: Only participants explicitly trusted by the owner bypass the lobby. Everyone else waits for approval regardless of authentication. + example: "trusted" Room: type: object @@ -285,10 +285,7 @@ components: description: URL-friendly room identifier (auto-generated) example: "aze-eere-zer" access_level: - type: string - readOnly: true - description: Room access level (always 'trusted' for API-created rooms) - example: "trusted" + $ref: '#/components/schemas/RoomAccessLevel' url: type: string format: uri @@ -316,6 +313,8 @@ components: type: string description: Default country code example: "US" + configuration: + $ref: '#/components/schemas/RoomConfiguration' OAuthError: type: object