api docs: Document the POST /api/v1/users/me/subscriptions endpoint.

There is a JavaScript equivalent for this endpoint but the npm
package has not yet been released.

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
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="curl">curl</li>
+<li data-language="python">Python</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+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"]'
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+```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']
+))
+
+```
+
+</div>
+
+</div>
+
+</div>
+
+## 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!}

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`"
+        }
     ]
 }

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
 

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.