From bca7683f58d87d7d347f0e70aaa2336c8cafbcbb Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Wed, 31 May 2023 14:03:52 +0200 Subject: [PATCH] api-docs: Revisions for feature level 161 changes. Revises the API changelog entry for feature level 161 to document the changes to `DELETE /users/me/subscriptions` and to explain more clearly what the new `can_remove_subscribers_group_id` parameter does. Updates the feature level 161 changes notes and related descriptions to include links and also more clearly explain the updates. Also, updates the `GET /user_groups` example to better reflect what is returned for system groups since this is now referenced in the `can_remove_subscribers_group_id` parameter description. The original API feature level 161 API documentation changes were made in commit c3759814be23ae and commit 73f11853ec4eec. --- api_docs/changelog.md | 17 +++++++----- zerver/openapi/zulip.yaml | 57 ++++++++++++++++++++++++--------------- 2 files changed, 46 insertions(+), 28 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 8842f014f8..cb88d046da 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -258,13 +258,16 @@ format used by the Zulip server that they are interacting with. **Feature level 161** -* [`PATCH /streams/{stream_id}`](/api/update-stream): Added - `can_remove_subscribers_group_id` parameter to support - changing `can_remove_subscribers_group` setting. -* [`POST /users/me/subscriptions`](/api/subscribe): Added - `can_remove_subscribers_group_id` parameter to set - `can_remove_subscribers_group` setting while creating - streams. +* [`POST /users/me/subscriptions`](/api/subscribe), + [`PATCH /streams/{stream_id}`](/api/update-stream): Added + `can_remove_subscribers_group_id` parameter to support setting and + changing the user group whose members can remove other subscribers + from the specified stream. +* [`DELETE /users/me/subscriptions`](/api/unsubscribe): Expanded the + situations where users can use this endpoint to unsubscribe other + users from a stream to include the case where the current user has + access to the stream and is a member of the user group specified by + the `can_remove_subscribers_group_id` for the stream. **Feature level 160** diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 234d013983..3a2db9f66a 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -8738,17 +8738,21 @@ paths: - Organization administrators can remove any user from any stream. - Users can remove a bot that they own from any stream that - the user can access. - - Users who can access a stream and are in the group with ID - `can_remove_subscribers_group_id` for that stream can - unsubscribe any user from that stream. + the user [can access](/help/stream-permissions). + - Users can unsubscribe any user from a stream if they [have + access](/help/stream-permissions) to the stream and are a + member of the [user group](/api/get-user-groups) specified + by the [`can_remove_subscribers_group_id`][can-remove-parameter] + for the stream. - **Changes**: Before Zulip 7.0 (feature level 161), - `can_remove_subscribers_group_id` was always the system group - for organization administrators. + **Changes**: Before Zulip 7.0 (feature level 161), the + `can_remove_subscribers_group_id` for all streams was always + the system group for organization administrators. Before Zulip 6.0 (feature level 145), users had no special privileges for managing bots that they own. + + [can-remove-parameter]: /api/subscribe#parameter-can_remove_subscribers_group_id x-curl-examples-parameters: oneOf: - type: include @@ -16154,21 +16158,29 @@ paths: "user_groups": [ { - "description": "Characters of Hamlet", + "description": "Owners of this organization", "id": 1, + "name": "@role:owners", + "members": [1], + "direct_subgroup_ids": [], + "is_system_group": true, + }, + { + "description": "Administrators of this organization, including owners", + "id": 2, + "name": "@role:administrators", + "members": [2], + "direct_subgroup_ids": [1], + "is_system_group": true, + }, + { + "description": "Characters of Hamlet", + "id": 3, "name": "hamletcharacters", "members": [3, 4], "direct_subgroup_ids": [], "is_system_group": false, }, - { - "description": "Moderators", - "id": 2, - "name": "other users", - "members": [1, 2], - "direct_subgroup_ids": [1, 2], - "is_system_group": true, - }, ], } /user_groups/{user_group_id}/subgroups: @@ -18910,12 +18922,15 @@ components: name: can_remove_subscribers_group_id in: query description: | - ID of the user group whose members are allowed to unsubscribe others - from the stream, if they have access to this stream, even if - they are not an organization administrator. + ID of the [user group](/api/get-user-groups) whose members are + allowed to unsubscribe others from the stream. Note that a user + who is a member of the specified user group must also [have + access](/help/stream-permissions) to the stream in order to + unsubscribe others. - This setting can currently only be set to system user groups - except `@role:internet` and `@role:owners` group. + This setting can currently only be set to user groups that are + system groups, except for the system groups named + `"@role:internet"` and `"@role:owners"`. **Changes**: New in Zulip 7.0 (feature level 161). schema: