mirror of https://github.com/zulip/zulip.git
api docs: Document the get-streams endpoint.
This commit documents the get-streams endpoint, which can be by making a GET request to /api/v1/streams. Note that in the code examples, JavaScript is missing an example for how to pass in the `include_` query parameters. That is because zulip-js's client.streams.retrieve function doesn't take any arguments and zulip-js does not export any function equivalent to client.call_endpoint in python-zulip-api/zulip.
This commit is contained in:
Eeshan Garg
showell
parent
3003d3d927
commit
e769a7eed2
|
|
@ -44,5 +44,31 @@
|
|||
"required":"Required",
|
||||
"example":"Hello"
|
||||
}
|
||||
],
|
||||
"get-all-streams.md":[
|
||||
{
|
||||
"argument":"include_public",
|
||||
"description":"Include all public streams. Default is `True`.",
|
||||
"required":"Optional",
|
||||
"example":"`True` or `False`"
|
||||
},
|
||||
{
|
||||
"argument":"include_subscribed",
|
||||
"description":"Include all streams that the user is subscribed to. Default is `True`.",
|
||||
"required":"Optional",
|
||||
"example":"`True` or `False`"
|
||||
},
|
||||
{
|
||||
"argument":"include_all_active",
|
||||
"description":"Include all active streams. The user must have administrative privileges to use this parameter. Default is `False`.",
|
||||
"required":"Optional",
|
||||
"example":"`True` or `False`"
|
||||
},
|
||||
{
|
||||
"argument":"include_default",
|
||||
"description":"Include all default streams for the user's realm. Default is `False`.",
|
||||
"required":"Optional",
|
||||
"example":"`True` or `False`"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,150 @@
|
|||
# Get all streams
|
||||
|
||||
Get all streams that the user has access to.
|
||||
|
||||
`GET {{ api_url }}/v1/streams`
|
||||
|
||||
## Arguments
|
||||
|
||||
**Note**: The following arguments are all URL query parameters.
|
||||
|
||||
{generate_api_arguments_table|arguments.json|get-all-streams.md}
|
||||
|
||||
## Usage examples
|
||||
<div class="code-section" markdown="1">
|
||||
<ul class="nav">
|
||||
<li data-language="curl">curl</li>
|
||||
<li data-language="python">Python</li>
|
||||
<li data-language="javascript">JavaScript</li>
|
||||
</ul>
|
||||
<div class="blocks">
|
||||
|
||||
<div data-language="curl" markdown="1">
|
||||
|
||||
```
|
||||
curl {{ api_url }}/v1/streams -u BOT_EMAIL_ADDRESS:BOT_API_KEY
|
||||
```
|
||||
|
||||
You may pass in one or more of the parameters mentioned above
|
||||
as URL query parameters, like so:
|
||||
|
||||
```
|
||||
curl {{ api_url }}/v1/streams?include_public=false \
|
||||
-u BOT_EMAIL_ADDRESS:BOT_API_KEY
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-language="python" markdown="1">
|
||||
|
||||
```
|
||||
#!/usr/bin/env python
|
||||
|
||||
import zulip
|
||||
import sys
|
||||
|
||||
# Keyword arguments 'email' and 'api_key' are not required if you are using ~/.zuliprc
|
||||
client = zulip.Client(email="othello-bot@example.com",
|
||||
api_key="a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
|
||||
site="{{ api_url }}")
|
||||
|
||||
# Get all streams that the user has access to
|
||||
print(client.get_streams())
|
||||
|
||||
# You may pass in one or more of the query parameters mentioned above
|
||||
# as keyword arguments, like so:
|
||||
print(client.get_streams(include_public=False))
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-language="javascript" markdown="1">
|
||||
More examples and documentation can be found [here](https://github.com/zulip/zulip-js).
|
||||
```js
|
||||
const zulip = require('zulip-js');
|
||||
|
||||
const config = {
|
||||
username: 'othello-bot@example.com',
|
||||
apiKey: 'a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5',
|
||||
realm: '{{ api_url }}'
|
||||
};
|
||||
|
||||
const client = zulip(config);
|
||||
|
||||
// Get all streams that the user has access to
|
||||
client.streams.retrieve().then(res => {
|
||||
console.log(res);
|
||||
});
|
||||
|
||||
```
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
## Response
|
||||
|
||||
#### Return values
|
||||
|
||||
* `stream_id`: The unique ID of a stream.
|
||||
* `name`: The name of a stream.
|
||||
* `description`: A short description of a stream.
|
||||
* `invite-only`: Specifies whether a stream is invite-only or not.
|
||||
Only people who have been invited can access an invite-only stream.
|
||||
|
||||
#### Example response
|
||||
|
||||
A typical successful JSON response may look like:
|
||||
|
||||
```
|
||||
{
|
||||
'result':'success',
|
||||
'streams':[
|
||||
{
|
||||
'stream_id':15,
|
||||
'name':'Denmark',
|
||||
'invite_only':False,
|
||||
'description':'A Scandinavian country'
|
||||
},
|
||||
{
|
||||
'stream_id':16,
|
||||
'name':'Rome',
|
||||
'invite_only':False,
|
||||
'description':'Yet another Italian city'
|
||||
},
|
||||
{
|
||||
'stream_id':17,
|
||||
'name':'Scotland',
|
||||
'invite_only':False,
|
||||
'description':'Located in the United Kingdom'
|
||||
},
|
||||
{
|
||||
'stream_id':18,
|
||||
'name':'Venice',
|
||||
'invite_only':False,
|
||||
'description':'A northeastern Italian city'
|
||||
},
|
||||
{
|
||||
'stream_id':19,
|
||||
'name':'Verona',
|
||||
'invite_only':False,
|
||||
'description':'A city in Italy'
|
||||
}
|
||||
],
|
||||
'msg':''
|
||||
}
|
||||
```
|
||||
|
||||
An example of a JSON response for when the user is not authorized
|
||||
to use the `include_all_active` parameter:
|
||||
|
||||
```
|
||||
{
|
||||
'code':'BAD_REQUEST',
|
||||
'result':'error',
|
||||
'msg':'User not authorized for this query'
|
||||
}
|
||||
```
|
||||
|
||||
{!invalid-api-key-json-response.md!}
|
||||
|
|
@ -8,6 +8,10 @@
|
|||
* [Stream message](/api/stream-message)
|
||||
* [Private message](/api/private-message)
|
||||
|
||||
#### Streams
|
||||
|
||||
* [Get all streams](/api/get-all-streams)
|
||||
|
||||
## Integrations
|
||||
|
||||
* [Overview](/api/integration-guide)
|
||||
|
|
|
|||
Loading…
Reference in New Issue