diff --git a/templates/zerver/api/add-subscriptions.md b/templates/zerver/api/add-subscriptions.md new file mode 100644 index 0000000000..9c8fdb84bb --- /dev/null +++ b/templates/zerver/api/add-subscriptions.md @@ -0,0 +1,158 @@ +# Add subscriptions + +Subscribe one or more users to one or more streams. + +`POST {{ api_url }}/v1/users/me/subcriptions` + +## Arguments + +{generate_api_arguments_table|arguments.json|add-subscriptions.md} + +## Usage examples +
+ +
+ +
+ +``` +curl {{ api_url }}/v1/users/me/subscriptions \ + -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ + -d 'subscriptions=[{"name": "Verona"}]' +``` + +To subscribe another user to a stream, you may pass in +the `principals` argument, like so: + +``` +curl {{ api_url }}/v1/users/me/subscriptions \ + -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ + -d 'subscriptions=[{"name": "Verona"}]' \ + -d 'principals=["ZOE@zulip.com"]' +``` + +
+ +
+ +```python +#!/usr/bin/env python + +import zulip + +# Download ~/zuliprc-dev from your dev server +client = zulip.Client(config_file="~/zuliprc-dev") + +# Subscribe to the streams "Verona" and "Denmark" +print(client.add_subscriptions( + streams=[ + {'name': 'Verona'}, + {'name': 'Denmark'} + ] +)) + +# To subscribe another user to a stream, you may pass in +# the `principals` argument, like so: +print(client.add_subscriptions( + streams=[ + {'name': 'Verona'}, + {'name': 'Denmark'} + ], + principals=['ZOE@zulip.org'] +)) + +``` + +
+ +
+ +
+ +## Response + +#### Return values + +* `subscribed`: A dictionary where the key is the email address of + the user/bot and the value is a list of the names of the streams + that were subscribed to as a result of the query. + +* `already_subscribed`: A dictionary where the key is the email address of + the user/bot and the value is a list of the names of the streams + that the user/bot is already subscribed to. + +* `unauthorized`: A list of names of streams that the requesting user/bot + was not authorized to subscribe to. + +#### Example response + +A typical successful JSON response may look like: + +``` +{ + 'msg':'', + 'result':'success', + 'already_subscribed':{ + + }, + 'subscribed':{ + 'sample-bot@localhost':[ + 'Denmark', + 'Verona' + ] + } +} +``` + +A typical successful JSON response when the user is already subscribed to +the streams specified: + +``` +{ + 'subscribed':{ + + }, + 'msg':'', + 'result':'success', + 'already_subscribed':{ + 'sample-bot@localhost':[ + 'Nonexistent', + 'Verona' + ] + } +} +``` + +A typical response for when the requesting user does not have access to +a private stream and `authorization_errors_fatal` is `True`: + +``` +{ + "msg":"Unable to access stream (yaar).", + "result":"error" +} +``` + +A typical response for when the requesting user does not have access to +a private stream and `authorization_errors_fatal` is `False`: + +``` +{ + "unauthorized":[ + "yaar" + ], + "subscribed":{ + + }, + "msg":"", + "result":"success", + "already_subscribed":{ + + } +} +``` + +{!invalid-api-key-json-response.md!} diff --git a/templates/zerver/api/arguments.json b/templates/zerver/api/arguments.json index f939aff43b..d97b6558e6 100644 --- a/templates/zerver/api/arguments.json +++ b/templates/zerver/api/arguments.json @@ -206,6 +206,37 @@ "required":"Optional", "example":"change_all" } - + ], + "add-subscriptions.md":[ + { + "argument":"subscriptions", + "description":"A list of dictionaries, where each dictionary contains key/value pairs specifying a particular stream to subscribe to. **Note**: This argument is called `streams` and not `subscriptions` in our Python API.", + "required":"Required", + "example":"[{'name': 'Verona'}]" + }, + { + "argument":"invite_only", + "description":"A boolean specifying whether the streams specified in `subscriptions` are invite-only or not. Default is `False`.", + "required":"Optional", + "example":"`True` or `False`" + }, + { + "argument":"announce", + "description":"If `announce` is `True` and one of the streams specified in `subscriptions` has to be created (i.e. doesn't exist to begin with), an announcement will be made notifying that a new stream was created.", + "required":"Optional", + "example":"`True` or `False`" + }, + { + "argument":"principals", + "description":"A list of email addresses of the users that will be subscribed to the streams specified in the `subscriptions` argument. Default is `[]`. If not provided, then the requesting user/bot is subscribed.", + "required":"Optional", + "example":"['ZOE@zulip.com']" + }, + { + "argument":"authorization_errors_fatal", + "description":"A boolean specifying whether authorization errors (such as when the requesting user is not authorized to access a private stream) should be considered fatal or not. Default is `True`, in which case an authorization error is reported as such. When set to `False`, the returned JSON payload indicates that there was an authorization error, but the response is still considered a successful one.", + "required":"Optional", + "example":"`True` or `False`" + } ] } diff --git a/templates/zerver/api/sidebar.md b/templates/zerver/api/sidebar.md index dd0d8a8b21..72679186d2 100644 --- a/templates/zerver/api/sidebar.md +++ b/templates/zerver/api/sidebar.md @@ -15,6 +15,7 @@ * [Get all streams](/api/get-all-streams) * [Get stream ID](/api/get-stream-id) * [Get subscribed streams](/api/get-subscribed-streams) +* [Add subscriptions](/api/add-subscriptions) #### Users diff --git a/zerver/tests/test_docs.py b/zerver/tests/test_docs.py index 6560c2b813..d5d51c3424 100644 --- a/zerver/tests/test_docs.py +++ b/zerver/tests/test_docs.py @@ -66,6 +66,7 @@ class DocPageTest(ZulipTestCase): self._test('/api/delete-queue', 'Delete a previously registered queue') self._test('/api/update-message', 'propagate_mode') self._test('/api/get-profile', 'takes no arguments') + self._test('/api/add-subscriptions', 'authorization_errors_fatal') self._test('/team/', 'industry veterans') self._test('/history/', 'Cambridge, Massachusetts') # Test the i18n version of one of these pages.