Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/templates/zerver/api/get-subscriptions.md

43 lines
939 B
Markdown
Raw Normal View History

api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
# Get subscribed streams
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
{generate_api_description(/users/me/subscriptions:get)}
api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
## Usage examples
api docs: Use Markdown extension for tabbed sections.
2018-09-17 16:27:32 +02:00
{start_tabs}
{tab|python}
api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
openapi: Remove /users/me/subscriptions from pending_endpoints. In commit 7c71e98, we added a special exception for the /users/me/subscriptions endpoint in the automatic validation test. By adding some extra documentation, we now remove this extra code, as well as the endpoint from the list of pending endpoints.
2019-07-19 07:02:10 +02:00
{generate_code_example(python)|/users/me/subscriptions:get|example}
api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
api docs: Use Markdown extension for tabbed sections.
2018-09-17 16:27:32 +02:00
{tab|js}
api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
More examples and documentation can be found [here](https://github.com/zulip/zulip-js).
js_examples: Migrate and test get_subscriptions example. Also, `send_message` example is altered to send a message to the stream 'social' to avoid getting a "first_message_id: null" in the response for `get_subscriptions` example, that caused `validate_against_openapi_schema` to throw an error.
2020-06-21 22:41:13 +02:00
{generate_code_example(javascript)|/users/me/subscriptions:get|example}
api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
api docs: Use Markdown extension for tabbed sections.
2018-09-17 16:27:32 +02:00
{tab|curl}
docs: Make get-subscribed-streams use curl example system.
2019-10-10 09:58:46 +02:00
{generate_code_example(curl, include=[""])|/users/me/subscriptions:get|example}
api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
subscriptions: Avoid sending unneeded subscriber information. The `users/me/subscriptions` endpoint accidentally started returning subscriber information for each stream. This is convenient, but unnecessarily costly for those clients which either don't need it (most API apps) or already acquire this information via /register (including Zulip's apps). This change removes that data set from the default response. Clients which had come to rely on it, or would like to rely on it in future, may still access it via an additional documented API parameter. Fixes #12917.
2019-08-08 21:58:38 +02:00
You may pass the `include_subscribers` query parameter as follows:
docs: Make get-subscribed-streams use curl example system.
2019-10-10 09:58:46 +02:00
{generate_code_example(curl)|/users/me/subscriptions:get|example}
subscriptions: Avoid sending unneeded subscriber information. The `users/me/subscriptions` endpoint accidentally started returning subscriber information for each stream. This is convenient, but unnecessarily costly for those clients which either don't need it (most API apps) or already acquire this information via /register (including Zulip's apps). This change removes that data set from the default response. Clients which had come to rely on it, or would like to rely on it in future, may still access it via an additional documented API parameter. Fixes #12917.
2019-08-08 21:58:38 +02:00
api docs: Use Markdown extension for tabbed sections.
2018-09-17 16:27:32 +02:00
{end_tabs}
api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
openapi_docs: Replace `argument` with `parameter`. The term `parameter` is a better word than `argument` for data passed to an API endpoint; this is why OpenAPI uses in their terminology. Replace `argument` with `parameter` in the API docs to improve their readability. Fixes #15435.
2020-06-18 15:35:25 +02:00
## Parameters
api docs: Move code examples farther up.
2018-01-20 22:03:05 +01:00
subscriptions: Avoid sending unneeded subscriber information. The `users/me/subscriptions` endpoint accidentally started returning subscriber information for each stream. This is convenient, but unnecessarily costly for those clients which either don't need it (most API apps) or already acquire this information via /register (including Zulip's apps). This change removes that data set from the default response. Clients which had come to rely on it, or would like to rely on it in future, may still access it via an additional documented API parameter. Fixes #12917.
2019-08-08 21:58:38 +02:00
{generate_api_arguments_table|zulip.yaml|/users/me/subscriptions:get}
api docs: Move code examples farther up.
2018-01-20 22:03:05 +01:00
api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
## Response
#### Return values
openapi: Add markdown extension for rendering return values in API docs. Currently response return values have to be written twice, once in the docs and once in zulip.yaml. Create a markdown extension so that the return values in api docs are rendered using content from zulip.yaml
2020-05-20 11:57:57 +02:00
{generate_return_values_table|zulip.yaml|/users/me/subscriptions:get}
api docs: Document the GET /users/me/subscriptions endpoint.
2017-12-30 01:19:43 +01:00
#### Example response
A typical successful JSON response may look like:
openapi: Remove /users/me/subscriptions from pending_endpoints. In commit 7c71e98, we added a special exception for the /users/me/subscriptions endpoint in the automatic validation test. By adding some extra documentation, we now remove this extra code, as well as the endpoint from the list of pending endpoints.
2019-07-19 07:02:10 +02:00
{generate_code_example|/users/me/subscriptions:get|fixture(200)}