feature request: API to modify membership of user groups, streams

[nikomatsakis]

Hello! On the rust project, we manage membership in our various teams and so forth via a central repository, so that commits to add members automatically adjust membership in the appropriate github teams and the like. I would like to have commits in that repository adjust membership of user groups or associated streams (especially private ones), but I've been told that there is no API for those kinds of synchronizations.

Apologies if the API exists already!

[zulipbot]

Hello @zulip/server-api members, this issue was labeled with the "area: documentation (api and integrations)" label, so you may want to check it out!

[timabbott]

Howdy @nikomatsakis!

Doing streams is possible with: https://zulipchat.com/api/subscribe and https://zulipchat.com/api/unsubscribe (see the second examples involving "principals"), with the complications that:

• You need to make sure the bot is subscribed to the relevant streams so that it has permissions to add users to them (our security model doesn't allow administrators to add users to private streams)
• You'll need to get the administrator role added to the bot (https://zulipchat.com/api/update-user can do it if you pass the bot's user ID) to have it able to remove users.
• You need to do the membership diffing yourself, using https://zulipchat.com/api/get-streams with include_subscribers: true to get the current list (you could imagine an API that just set the stream membership, for example, and took care of the diff part for you).

For user groups, you need the undocumented POST /user_groups/{user_group_id}/members endpoint; you can easily see how it works using the Network tab in your browser when managing a user group.

I think this is something we should have a supported interface for; it's relevant in a lot of corporate environments. If you decide to write something with the Python API before we do something here, we would definitely love a contribution to add a sync_stream_membership(stream_id, user_ids) method to https://github.com/zulip/python-zulip-api/blob/master/zulip/zulip/__init__.py that we can then document.

@akashaviator can you prioritize documenting that missing user group membership endpoint?

[t-vi]

I looked at managing user groups from a bot but it seems that a bot cannot list user groups because the function serving the /user_groups/ endpoint, get_user_group in views/user_groups.py, is decorated with @require_member_or_admin, which excludes bots:

https://github.com/zulip/zulip/blob/706ec9714c76d98c2ac230c3a5adf35dfd0c438a/zerver/views/user_groups.py#L44-L48

and then the bot block

https://github.com/zulip/zulip/blob/706ec9714c76d98c2ac230c3a5adf35dfd0c438a/zerver/decorator.py#L551

Would it make sense to open this for admin bots? (While I can see that you would be limiting bots in general, I am not quite sure I understand the rationale for limiting bots designated as admin nor how I might work around that limitation (I guess my idea for permissions would be "block by default" and then ORing decorators by creating a list attribute on the function and amending to that with chained decorators, so I could decorate the group editing callbacks with something like

@allow_member_or_admin
@allow_admin_bots

But that is getting off topic.)

[timabbott]

I think it makes sense to just change this model; made a note of that in the #19525 issue.

@MSurfer20 FYI that we should also prioritize documenting all the user group related endpoints, since they will be an important focus for us with #19525.

[MiaIsHappy]

Hi @zulipbot I'd like to work on this issue.

I am a candidate for the Outreachy program. I would like to be part of the Extend and polish Zulip's OpenAPI documentation project. I think this issue is something I can contribute as a new member of the community.

My skill sets are Python, Web, and technical writing.

[alya]

@MarisaShang03 Welcome! Please take a look at the Zulip contributor guide for a detailed walk-through of how to get started. I also recommend checking out the #Outreachy stream in the Zulip development community.