paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-25 00:53:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
There is a JavaScript equivalent for this endpoint but the npm
package has not yet been released.
This commit is contained in:
Eeshan Garg
2018-01-06 19:19:14 -03:30
committed by showell
parent ae59b08316
commit a01f8c088a
4 changed files with 192 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
templates/zerver/api/add-subscriptions.md Normal file
View File

@@ -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!}

33
templates/zerver/api/arguments.json
View File

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

1
templates/zerver/api/sidebar.md
View File

@@ -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

1
zerver/tests/test_docs.py
View File

@@ -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.