Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/zerver/openapi/zulip.yaml

4772 lines
180 KiB
YAML
Raw Normal View History

api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
# This file contains the API definitions for the Zulip REST API.
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
#
docs: Convert many http URLs to https. Signed-off-by: Anders Kaseorg <anders@zulipchat.com>
2020-03-27 01:32:21 +01:00
# For details on the OpenAPI specification, see https://swagger.io/specification
Explain how to add Swagger REST API doc coverage in zulip.yaml. Introduce Swagger UI and the Swagger/OpenAPI specification. Explain the structure of zulip.yaml and show examples of different sections of the file. This is a new file in /docs not yet included in the Read the Docs table of contents. Where it should go should be determined as we iterate on the Swagger UI integration and expand REST API doc coverage using it. For more on Swagger UI and how Zulip uses it, see: https://github.com/zulip/zulip/issues/3474 https://github.com/zulip/zulip/pull/3397 With some minor tweaks to advertise this by tabbott.
2017-02-24 03:39:44 +01:00
#
# Our own documentation lives at
#
docs: Extract a Writing Documentation top-level section. This should make this easier to find, and also makes "Subsystems" a bit smaller of a catch-all.
2019-05-30 00:39:50 +02:00
# https://zulip.readthedocs.io/en/latest/documentation/openapi.html
Explain how to add Swagger REST API doc coverage in zulip.yaml. Introduce Swagger UI and the Swagger/OpenAPI specification. Explain the structure of zulip.yaml and show examples of different sections of the file. This is a new file in /docs not yet included in the Read the Docs table of contents. Where it should go should be determined as we iterate on the Swagger UI integration and expand REST API doc coverage using it. For more on Swagger UI and how Zulip uses it, see: https://github.com/zulip/zulip/issues/3474 https://github.com/zulip/zulip/pull/3397 With some minor tweaks to advertise this by tabbott.
2017-02-24 03:39:44 +01:00
#
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
openapi: 3.0.1
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
info:
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
version: 1.0.0
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
title: Zulip REST API
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Powerful open source group chat
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
contact:
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
url: https://zulipchat.com
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
servers:
openapi: Fix servers section to work in online editor.
2020-04-28 23:27:43 +02:00
# Zulip Cloud
- url: 'https://{subdomain}.zulipchat.com/api/v1'
variables:
subdomain:
default: example
# Self-hosted
- url: '{server}/api/v1'
variables:
server:
default: https://
# chat.zulip.org
- url: 'https://chat.zulip.org/api/v1'
# Development server
- url: 'http://localhost:9991/api/v1'
openapi: Specify securityScheme for the API in root level. We used to specify the securityScheme for each REST operation seperately. This is unecessary as the securityScheme can be specified in root level and would be automatically applied to all operations. This also prevents us accidentally not specifying the securityScheme for some operations and was the case for /users/me/subscriptions PATCH endpoint. The root level securityScheme can be also overriden in the operational level when necessary. swagger.io/docs/specification/authentication/#security
2019-12-04 12:27:15 +01:00
security:
- basicAuth: []
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
#######################
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
# Endpoint definitions
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
#######################
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
paths:
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
/fetch_api_key:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: fetch_api_key
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["authentication"]
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
description: |
Given a username and password, fetch the user's API key.
Used to authenticate the mobile and terminal apps when the server
has EmailAuthBackend or LDAPAuthBackend enabled.
parameters:
- name: username
in: query
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
The username to be used for authentication (typically, the email
address, but it could be an LDAP username).
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
schema:
type: string
required: true
- name: password
in: query
schema:
type: string
description: |
The user's Zulip password (or LDAP password, if LDAP authentication is in use).
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
/dev_fetch_api_key:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: dev_fetch_api_key
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["authentication"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
For easy testing of mobile apps and other clients and against Zulip
development servers, we support fetching a Zulip API key for any user
on the development server without authentication (so that they can
implement analogues of the one-click login process available for Zulip
development servers on the web).
**Note:** This endpoint is only available on Zulip development
servers; for obvious security reasons it will always return an error
in a Zulip production server.
`POST {{ api_url }}/v1/dev_fetch_api_key`
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
parameters:
- name: username
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The email address for the user that owns the API key.
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
schema:
type: string
example: iago@zulip.com
required: true
openapi: Specify securityScheme for the API in root level. We used to specify the securityScheme for each REST operation seperately. This is unecessary as the securityScheme can be specified in root level and would be automatically applied to all operations. This also prevents us accidentally not specifying the securityScheme for some operations and was the case for /users/me/subscriptions PATCH endpoint. The root level securityScheme can be also overriden in the operational level when necessary. swagger.io/docs/specification/authentication/#security
2019-12-04 12:27:15 +01:00
security: []
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
/events:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_events
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
`GET {{ api_url }}/v1/events`
This endpoint allows you to receive new events from
[a registered event queue](/api/register-queue).
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
parameters:
api_docs: Add "QueueId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "queue_id" in components.
2020-04-18 17:35:53 +02:00
- $ref: '#/components/parameters/QueueId'
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
- name: last_event_id
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The highest event ID in this queue that you've received and
wish to acknowledge. See the [code for
`call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/master/zulip/zulip/__init__.py)
in the [zulip Python
module](https://github.com/zulip/python-zulip-api) for an
example implementation of correctly processing each event
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
exactly once.
schema:
type: integer
example: -1
- name: dont_block
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Set to `true` if the client is requesting a nonblocking reply. If not
specified, the request will block until either a new event is available
or a few minutes have passed, in which case the server will send the
client a heartbeat event.
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
schema:
type: boolean
default: false
example: true
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
events:
type: array
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
An array of `event` objects (possibly zero-length if `dont_block` is
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
set) with IDs newer than `last_event_id`. Event IDs are
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
guaranteed to be increasing, but they are not guaranteed to be
consecutive.
openapi: Pass validation of zulip.yaml on openapi-generator. The openapi-generator has an additional set of requirements for validation. Make changes in zulip.yaml accordingly.
2020-04-18 12:46:15 +02:00
items:
type: object
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
- example:
{
"events": [
{
"id": 0,
"message": {
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
api docs: Change Shakespeare quote. The previous quote doesn't come off well if you don't know the reference (which the majority of our users will not).
2018-10-23 00:42:54 +02:00
"content": "I come not, friends, to steal away your hearts.",
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
"content_type": "text/x-markdown",
"display_recipient": "Denmark",
"id": 12345678,
"recipient_id": 12314,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"sender_short_name": "othello-bot",
api docs: Advertise "topic" argument instead of "subject" on /messages. They have the same meaning but we're transitioning away from the "subject" terminology, so we should advertise "topic" in docs.
2019-12-30 23:06:50 +01:00
"topic": "Castle",
api: Rename subject_links to topic_links. Fixes #13588
2020-02-07 13:09:17 +01:00
"topic_links": [],
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
"timestamp": 1375978403,
"type": "stream"
},
"type": "message"
},
{
"id": 1,
"message": {
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
api docs: Change Shakespeare quote. The previous quote doesn't come off well if you don't know the reference (which the majority of our users will not).
2018-10-23 00:42:54 +02:00
"content": "With mirth and laughter let old wrinkles come.",
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
"content_type": "text/x-markdown",
"display_recipient": [
{
"email": "hamlet@example.com",
"full_name": "Hamlet of Denmark",
"id": 31572,
"short_name": "hamlet"
}
],
"id": 12345679,
"recipient_id": 18391,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"sender_short_name": "othello-bot",
"subject": "",
api: Rename subject_links to topic_links. Fixes #13588
2020-02-07 13:09:17 +01:00
"topic_links": [],
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
"timestamp": 1375978404,
"type": "private"
},
"type": "message"
}
],
"msg": "",
"result": "success"
}
'400':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Bad request.
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
content:
application/json:
schema:
$ref: '#/components/schemas/BadEventQueueIdError'
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
delete:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: delete_queue
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Delete a previously registered queue.
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
`DELETE {{ api_url }}/v1/events`
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
parameters:
api_docs: Add "QueueId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "queue_id" in components.
2020-04-18 17:35:53 +02:00
- $ref: '#/components/parameters/QueueId'
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/BadEventQueueIdError'
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
/get_stream_id:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_stream_id
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Get the unique ID of a given stream.
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
`GET {{ api_url }}/v1/get_stream_id`
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
parameters:
api_docs: Add "Stream" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream" in components.
2020-04-18 17:59:13 +02:00
- $ref: '#/components/parameters/Stream'
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
required: true
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
stream_id:
type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The ID of the given stream.
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
- example:
{
"msg": "",
"result": "success",
"stream_id": 15
}
'400':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Bad request.
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream name 'nonexistent'",
"result": "error"
}
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
/mark_all_as_read:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: mark_all_as_read
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Marks all of the current user's unread messages as read.
`POST {{ api_url }}/v1/mark_all_as_read`
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
/mark_stream_as_read:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: mark_stream_as_read
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Mark all the unread messages in a stream as read.
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
parameters:
api_docs: Add "StreamIdInQuery" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in query) in components.
2020-04-19 10:01:44 +02:00
- $ref: '#/components/parameters/StreamIdInQuery'
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
/mark_topic_as_read:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: mark_topic_as_read
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Mark all the unread messages in a topic as read.
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
parameters:
api_docs: Add "StreamIdInQuery" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in query) in components.
2020-04-19 10:01:44 +02:00
- $ref: '#/components/parameters/StreamIdInQuery'
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
required: true
- name: topic_name
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The name of the topic whose messages should be marked as read.
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
schema:
type: string
example: new coffee machine
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
/messages:
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_messages
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Fetch message history from a Zulip server.
`GET {{ api_url }}/v1/messages`
This `GET /api/v1/messages` endpoint is the primary way to fetch
message history from a Zulip server. It is useful both for Zulip
clients (e.g. the web, desktop, mobile, and terminal clients) as well
as bots, API clients, backup scripts, etc.
By specifying a [narrow filter](/api/construct-narrow), you can use
this endpoint to fetch the messages matching any search query that is
supported by Zulip's powerful full-text search backend.
When a narrow is not specified, it can be used to fetch a user's
message history (We recommend paginating to 1000 messages at a time).
In either case, you specify an `anchor` message (or ask the server to
calculate the first unread message for you and use that as the
anchor), as well as a number of messages before and after the anchor
message. The server returns those messages, sorted by message ID, as
well as some metadata that makes it easy for a client to determine
whether there are more messages matching the query that were not
returned due to the `num_before` and `num_after` limits.
We recommend using `num_before <= 1000` and `num_after <= 1000` to
avoid generating very large HTTP responses. A maximum of 5000 messages
can be obtained per request; attempting to exceed this will result in an
error.
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
parameters:
- name: anchor
in: query
docs: Document changes in the API made since Zulip 2.1.x. This is important documentation for anyone working on writing clients for the Zulip APIs that wants to support older releases.
2020-03-27 01:45:03 +01:00
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
Integer message ID to anchor fetching of new messages. Supports special
string values for when the client wants the server to compute the anchor
to use:
docs: Document changes in the API made since Zulip 2.1.x. This is important documentation for anyone working on writing clients for the Zulip APIs that wants to support older releases.
2020-03-27 01:45:03 +01:00
* `newest`: The most recent message.
* `oldest`: The oldest message.
* `first_unread`: The oldest unread message matching the
query, if any; otherwise, the most recent message.
api: Document new get_messages oldest/newest API feature. While we're at it, we make the examples more sensible.
2020-01-29 02:58:17 +01:00
The special values of `'newest'` and `'oldest'` are also supported
for anchoring the query at the most recent or oldest messages.
docs: Document changes in the API made since Zulip 2.1.x. This is important documentation for anyone working on writing clients for the Zulip APIs that wants to support older releases.
2020-03-27 01:45:03 +01:00
api docs: Add an API changelog page. I imagine this can be improved in various ways, but I've initialized this with all the **Changes** entries recorded in either zulip.yaml or the rest of the API documentation, and I expect we'll be able to iterate on this effectively. It'll also be useful as a record of changes that we should remember to document the API documentation as we document more endpoints that currently don't discuss these issues. While working on this, I fixed various issues where feature levels could be mentioned or endpoints didn't properly document changes.
2020-04-29 05:55:42 +02:00
**Changes**: String values are new in Zulip 2.2 (feature level 1). The
docs: Document changes in the API made since Zulip 2.1.x. This is important documentation for anyone working on writing clients for the Zulip APIs that wants to support older releases.
2020-03-27 01:45:03 +01:00
`first_unread` functionality was supported in Zulip 2.1.x
and older by not sending anchor and using use_first_unread_anchor.
In Zulip 2.1.x and older, `oldest` can be emulated with
`anchor=0`, and `newest` with `anchor=10000000000000000`
(that specific large value works around a bug in Zulip
2.1.x and older in the `found_newest` return value).
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
schema:
narrow: Add support for passing oldest/newest for anchor. A wart that has long been present inin Zulip's get_messages API is how to request "the latest messages" in the API. Previously, the recommendation was basically to pass anchor=10000000000000000 (for an appropriately huge number). An accident of the server's implementation meant that specific number of 0s was actually important to avoid a buggy (or at least wasteful) value of found_newest=False if the query had specified num_after=0 (since we didn't check). This was the cause of the mobile issue https://github.com/zulip/zulip-mobile/issues/3654. The solution is to allow passing a special value of anchor='newest', basically a special string-type value that the server can interpret as meaning the user precisely just wants the most recent messages. We also add an analogous anchor='oldest' or similar to avoid folks needing to write a somewhat ugly anchor=0 for fetching the very first messages. We may want to also replace the use_first_unread_anchor argument to be a "first_unread" value for the anchor parameter. While it's not always ideal to make a value have a variable type like this, in this case it seems like a really clean way to express the idea of what the user is asking for in the API.
2020-01-28 06:37:25 +01:00
oneOf:
- type: string
- type: integer
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
example: 42
- name: num_before
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The number of messages with IDs less than the anchor to retrieve.
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
schema:
type: integer
example: 4
required: true
- name: num_after
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The number of messages with IDs greater than the anchor to retrieve.
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
schema:
type: integer
example: 8
required: true
- name: narrow
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The narrow where you want to fetch the messages from. See how to
[construct a narrow](/api/construct-narrow).
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
schema:
type: array
items:
type: object
default: []
openapi: Migrate /messages to use the new cURL example system. Now that we can create cURL examples based on the OpenAPI documentation. We can begin using simple one line tags in the documentation instead of manually creating cURL examples. Fixes part of #12878.
2019-08-02 14:47:18 +02:00
example: [{"operand": "Denmark", "operator": "stream"}]
api_docs: Add "ClientGravatar" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "client_gravatar" in components.
2020-04-19 11:21:51 +02:00
- $ref: '#/components/parameters/ClientGravatar'
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
- name: apply_markdown
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
If `true`, message content is returned in the rendered HTML
format. If `false`, message content is returned in the raw
markdown-format text that user entered.
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
schema:
type: boolean
default: true
example: false
docs: Document changes in the API made since Zulip 2.1.x. This is important documentation for anyone working on writing clients for the Zulip APIs that wants to support older releases.
2020-03-27 01:45:03 +01:00
- name: use_first_unread_anchor
in: query
description: |
Legacy way to specify `anchor="first_unread"` in Zulip 2.1.x and older.
Whether to use the (computed by the server) first unread message
matching the narrow as the `anchor`. Mutually exclusive with `anchor`.
**Changes**: Deprecated in Zulip 2.2, replaced by
`anchor="first_unread"` instead.
schema:
type: boolean
default: false
example: true
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
anchor:
type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The same `anchor` specified in the request (or the computed one, if
`use_first_unread_anchor` is `true`).
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
found_newest:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether the `messages` list includes the very newest messages matching
the narrow (used by clients that paginate their requests to decide
whether there are more messages to fetch).
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
found_oldest:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether the `messages` list includes the very oldest messages matching
the narrow (used by clients that paginate their requests to decide
whether there are more messages to fetch).
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
found_anchor:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether the anchor message is included in the
response. If the message with the ID specified
in the request does not exist or did not match
the narrow, this will be false.
messages: Add history_limited flag to messages response. The purpose of this commit is to pass information to the frontend whether the message response recieved has been limited due to plan restrictions or not. To implement this, the backend for limiting the message history had to be rewritten as we used to fetch only the message rows whose id was greater than first_visible_message_id. The filtered rows gives us no information on whether the message history was limited or not. So the backend was rewritten to not do any restriction of limiting the message rows while making the query. The limiting of rows is now done in post_process_limited_query which will also return back the value of history_limited flag. Tweaked by tabbott to note a few cases where the results are incorrect. I'm merging this despite those, because those cases don't impact the correctness of the feature, and it may have tricky performance implications to fix correctly.
2018-09-19 14:23:02 +02:00
history_limited:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether the message history was limited due to
plan restrictions. This flag is set to `true`
only when the oldest messages(`found_oldest`)
messages: Add history_limited flag to messages response. The purpose of this commit is to pass information to the frontend whether the message response recieved has been limited due to plan restrictions or not. To implement this, the backend for limiting the message history had to be rewritten as we used to fetch only the message rows whose id was greater than first_visible_message_id. The filtered rows gives us no information on whether the message history was limited or not. So the backend was rewritten to not do any restriction of limiting the message rows while making the query. The limiting of rows is now done in post_process_limited_query which will also return back the value of history_limited flag. Tweaked by tabbott to note a few cases where the results are incorrect. I'm merging this despite those, because those cases don't impact the correctness of the feature, and it may have tricky performance implications to fix correctly.
2018-09-19 14:23:02 +02:00
matching the narrow is fetched.
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
messages:
type: array
items:
type: object
openapi_responses: Fix get_messages.
2020-05-27 17:56:50 +02:00
- properties:
anchor:
type: integer
description: |
The same `anchor` specified in the request (or the computed one, if
`use_first_unread_anchor` is `true`).
found_newest:
type: boolean
description: |
Whether the `messages` list includes the very newest messages matching
the narrow (used by clients that paginate their requests to decide
whether there are more messages to fetch).
found_oldest:
type: boolean
description: |
Whether the `messages` list includes the very oldest messages matching
the narrow (used by clients that paginate their requests to decide
whether there are more messages to fetch).
found_anchor:
type: boolean
description: |
Whether the anchor message is included in the
response. If the message with the ID specified
in the request does not exist or did not match
the narrow, this will be false.
history_limited:
type: boolean
description: |
Whether the message history was limited due to
plan restrictions. This flag is set to `true`
only when the oldest messages(`found_oldest`)
matching the narrow is fetched.
messages:
type: array
description: |
an array of `message` objects, each containing the following
fields:
items:
type: object
properties:
avatar_url:
type: string
description: |
The URL of the user's avatar.
client:
type: string
description: |
A Zulip "client" string, describing what Zulip client
sent the message.
content:
type: string
description: |
The content/body of the message.
content_type:
type: string
description: |
The HTTP `content_type` for the message content. This
will be `text/html` or `text/x-markdown`, depending on
whether `apply_markdown` was set.
display_recepient:
oneOf:
- type: string
- type: array
items:
type: object
description: |
Data on the recipient of the message;
either the name of a stream or a dictionary containing basic data on
the users who received the message.
flags:
type: array
description: |
The user's [message flags][message-flags] for the message.
items:
type: string
id:
type: integer
description: |
The unique message ID. Messages should always be
displayed sorted by ID.
is_me_message:
type: boolean
description: |
Whether the message is a [/me status message][status-messages]
reactions:
type: array
description: |
Data on any reactions to the message.
items:
type: object
properties:
emoji_code:
type: integer
description: |
An encoded version of the emoji's unicode codepoint.
emoji_name:
type: string
description: |
Name of the emoji.
reaction_type:
type: string
description: |
If the reaction uses a [custom emoji](/help/add-custom-emoji),
`reaction_type` will be set to `realm_emoji`.
user_id:
type: integer
description: |
The ID of the user who added the reaction.
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
openapi_responses: Fix get_messages.
2020-05-27 17:56:50 +02:00
**Changes**: New in Zulip 2.2 (feature level 2). The `user`
object is deprecated and will be removed in the future.
user:
type: object
description: |
Dictionary with data on the user who added the reaction, including
the user ID as the `id` field. **Note**: In the [events
API](/api/get-events-from-queue), this `user` dictionary
confusing had the user ID in a field called `user_id`
instead. We recommend ignoring fields other than the user
ID. **Deprecated** and to be removed in a future release
once core clients have migrated to use the `user_id` field.
recipient_id:
type: integer
description: |
A unique ID for the set of users receiving the
message (either a stream or group of users). Useful primarily
for hashing.
sender_email:
type: string
description: |
The Zulip display email address of the message's sender.
sender_full_name:
type: string
description: |
The full name of the message's sender.
sender_id:
type: integer
description: |
The user ID of the message's sender.
sender_realm_str:
type: string
description: |
A string identifier for the realm the sender is in. Unique only within
the context of a given Zulip server.
E.g. on `example.zulip.com`, this will be `example`.
sender_short_name:
type: string
description: |
Reserved for future use.
stream_id:
type: integer
description: |
Only present for stream messages; the ID of the stream.
subject:
type: string
description: |
The `topic` of the message (only present for stream
messages). The field name is a legacy holdover from when topics were
called "subjects" and will eventually change.
topic_links:
type: array
items:
type: string
description: |
Data on any links to be included in the `topic`
line (these are generated by [custom linkification
filters][linkification-filters] that match content in the
message's topic.)
**Changes**: New in Zulip 2.2 (feature level 1).
Previously, this field was called `subject_links`;
clients are recommended to rename `subject_links`
to `topic_links` if present for compatibility with
older Zulip servers.
submessages:
type: array
items:
type: string
description: |
Data used for certain experimental Zulip integrations.
timestamp:
type: integer
description: |
The UNIX timestamp for when the message was sent,
in UTC seconds.
type:
type: string
description: |
The type of the message: `stream` or `private`.
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
- example:
{
"anchor": 21,
"found_newest": true,
"found_anchor": true,
"result": "success",
"msg": "",
"messages": [
{
"subject": "",
"sender_realm_str": "zulip",
"type": "private",
"content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
"flags": [
"read"
],
"id": 16,
"display_recipient": [
{
"short_name": "hamlet",
"id": 4,
"is_mirror_dummy": false,
"email": "hamlet@zulip.com",
"full_name": "King Hamlet"
},
{
"short_name": "iago",
"id": 5,
"is_mirror_dummy": false,
"email": "iago@zulip.com",
"full_name": "Iago"
},
{
"short_name": "prospero",
"id": 8,
"is_mirror_dummy": false,
"email": "prospero@zulip.com",
"full_name": "Prospero from The Tempest"
}
],
"content_type": "text/html",
"is_me_message": false,
"sender_short_name": "hamlet",
"timestamp": 1527921326,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 27,
api: Rename subject_links to topic_links. Fixes #13588
2020-02-07 13:09:17 +01:00
"topic_links": [],
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": []
},
{
"subject": "Verona3",
"stream_id": 5,
"sender_realm_str": "zulip",
"type": "stream",
"content": "<p>Wait, is this from the frontend js code or backend python code</p>",
"flags": [
"read"
],
"id": 21,
"display_recipient": "Verona",
"content_type": "text/html",
"is_me_message": false,
"sender_short_name": "hamlet",
"timestamp": 1527939746,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 20,
api: Rename subject_links to topic_links. Fixes #13588
2020-02-07 13:09:17 +01:00
"topic_links": [],
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": []
}
]
}
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: send_message
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Send a stream or a private message.
`POST {{ api_url }}/v1/messages`
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
parameters:
- name: type
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The type of message to be sent. `private` for a private message and
`stream` for a stream message.
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
schema:
type: string
enum:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
- private
- stream
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
example: private
required: true
- name: to
in: query
docs: Update API documention to note changes in Zulip 2.1.0.
2020-03-27 02:02:20 +01:00
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
For stream messages, either the name or integer ID of the stream. For
private messages, either a list containing integer user IDs or a list
containing string email addresses.
docs: Update API documention to note changes in Zulip 2.1.0.
2020-03-27 02:02:20 +01:00
api docs: Add an API changelog page. I imagine this can be improved in various ways, but I've initialized this with all the **Changes** entries recorded in either zulip.yaml or the rest of the API documentation, and I expect we'll be able to iterate on this effectively. It'll also be useful as a record of changes that we should remember to document the API documentation as we document more endpoints that currently don't discuss these issues. While working on this, I fixed various issues where feature levels could be mentioned or endpoints didn't properly document changes.
2020-04-29 05:55:42 +02:00
**Changes**: Support for using user/stream IDs was added in Zulip 2.0.0.
openapi: Rectify wrong examples and schemas. Some examples mentioned in zulip.yaml did not match their schema. Change either the schema or the example so that all examples are valid with respect to their schemas.
2020-05-11 14:14:12 +02:00
content:
application/json:
schema:
type: array
items:
type: integer
example: [9, 10]
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
required: true
api_docs: Add "Topic" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "topic" in components.
2020-04-18 11:14:08 +02:00
- $ref: '#/components/parameters/Topic'
api_docs: Add "Content" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "content" in components.
2020-04-19 11:46:51 +02:00
- $ref: '#/components/parameters/Content'
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
id:
type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi_responses: Fix send_message.
2020-05-25 20:23:18 +02:00
The unique ID assigned to the sent message.
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
- example:
{
"msg": "",
"id": 42,
"result": "success"
}
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
'400':
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
description: Bad request.
content:
application/json:
schema:
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
oneOf:
- $ref: '#/components/schemas/NonExistingStreamError'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid email 'eeshan@zulip.com'",
"result": "error"
}
docs: Document /get_stream_id API endpoint.
2017-06-25 21:00:55 +02:00
/messages/{message_id}:
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_raw_message
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Get the raw content of a message.
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
`GET {{ api_url }}/v1/messages/{msg_id}`
This is a rarely-used endpoint relevant for clients that primarily
work with HTML-rendered messages but might need to occasionally fetch
the message's raw markdown (e.g. for pre-filling a message-editing
UI).
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
parameters:
api_docs: Add "MessageId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "message_id" in components.
2020-04-20 16:46:14 +02:00
- $ref: '#/components/parameters/MessageId'
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
raw_content:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The raw content of the message.
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
- example:
{
"raw_content": "**Don't** forget your towel!",
"result": "success",
"msg": ""
}
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidMessageError'
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_message
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Edit/update the content or topic of a message.
`PATCH {{ api_url }}/v1/messages/{msg_id}`
`{msg_id}` in the above URL should be replaced with the ID of the
message you wish you update.
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
parameters:
api_docs: Add "MessageId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "message_id" in components.
2020-04-20 16:46:14 +02:00
- $ref: '#/components/parameters/MessageId'
api_docs: Add "Topic" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "topic" in components.
2020-04-18 11:14:08 +02:00
- $ref: '#/components/parameters/Topic'
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
- name: propagate_mode
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
"Which message(s) should be edited: just the one indicated in
`message_id`, messages in the same topic that had been sent after this
one, or all of them."
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
schema:
type: string
enum:
- change_one
- change_later
- change_all
default: change_one
example: change_all
api_docs: Add "Content" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "content" in components.
2020-04-19 11:46:51 +02:00
- $ref: '#/components/parameters/Content'
api_docs: Add "StreamIdInQuery" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in query) in components.
2020-04-19 10:01:44 +02:00
- $ref: '#/components/parameters/StreamIdInQuery'
docs: Document /streams/{stream_id} API endpoint.
2017-06-27 03:48:27 +02:00
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
docs: Document /streams/{stream_id} API endpoint.
2017-06-27 03:48:27 +02:00
'400':
description: Bad request.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
content:
application/json:
schema:
allOf:
api docs: Migrate /message/{message_id}:patch. Most part of "/message/{message_id}" is migrated to OpenAPI. This commit migrated the remaning payload "update-message-edit-permission-error" from "api/fixtures.json" to OpenAPI. This commit also fixes an error schema in "zulip.yaml" for this payload.
2020-03-15 17:28:23 +01:00
- $ref: '#/components/schemas/CodedError'
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
- properties:
msg:
enum:
- Your organization has turned off message editing
- You don't have permission to edit this message
- The time limit for editing this message has past
- Nothing to change
- Topic can't be empty
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
- example:
{
api docs: Fix indentation.
2018-06-06 18:17:58 +02:00
"code": "BAD_REQUEST",
"msg": "You don't have permission to edit this message",
"result": "error"
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
}
api docs: Document the DELETE /messages/<message_id> endpoint.
2018-06-26 16:30:46 +02:00
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: delete_message
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Permanently delete a message.
`DELETE {{ api_url }}/v1/messages/{msg_id}`
This API corresponds to the
[delete a message completely][delete-completely] feature documented in
the Zulip Help Center.
api docs: Document the DELETE /messages/<message_id> endpoint.
2018-06-26 16:30:46 +02:00
parameters:
api_docs: Add "MessageId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "message_id" in components.
2020-04-20 16:46:14 +02:00
- $ref: '#/components/parameters/MessageId'
api docs: Document the DELETE /messages/<message_id> endpoint.
2018-06-26 16:30:46 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
'400':
api docs: Document the DELETE /messages/<message_id> endpoint.
2018-06-26 16:30:46 +02:00
description: Bad request.
content:
application/json:
schema:
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
oneOf:
- $ref: '#/components/schemas/InvalidMessageError'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "You don't have permission to delete this message",
"result": "error"
}
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
/messages/{message_id}/history:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_message_history
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Fetch the message edit history of a previously edited message.
`GET {{ api_url }}/v1/messages/{message_id}/history`
Note that edit history may be disabled in some organizations; see the
[Zulip Help Center documentation on editing messages][edit-settings].
[edit-settings]: /help/view-a-messages-edit-history
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
parameters:
api_docs: Add "MessageId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "message_id" in components.
2020-04-20 16:46:14 +02:00
- $ref: '#/components/parameters/MessageId'
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
message_history:
type: array
items:
type: object
openapi_responses: Fix get_message_history.
2020-05-27 16:59:01 +02:00
properties:
topic:
type: string
description: |
the topic for the message.
content:
type: string
description: |
the body of the message.
rendered_content:
type: string
description: |
the already rendered, HTML version of `content`.
prev_content:
type: string
description: |
the body of the message before being edited.
prev_rendered_content:
type: string
description: |
the already rendered, HTML version of
`prev_content`.
user_id:
type: integer
description: |
the ID of the user that made the edit.
content_html_diff:
type: string
description: |
an HTML diff between this version of the message
and the previous one.
timestamp:
type: integer
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
the UNIX timestamp for this edit.
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A chronologically sorted array of `snapshot`
objects, each one with the values of the
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
message after the edit.
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
- example:
{
"message_history": [
{
"content": "Hello!",
"topic": "party at my houz",
"rendered_content": "<p>Hello!</p>",
"timestamp": 1530129122,
"user_id": 5
},
{
"topic": "party at my house",
"content": "Howdy!",
"prev_content": "Hello!",
"rendered_content": "<p>Howdy!</p>",
"user_id": 5,
"prev_rendered_content": "<p>Hello!</p>",
"content_html_diff": "<div><p><span class=\"highlight_text_inserted\">Howdy!</span></p> <p><span class=\"highlight_text_deleted\">Hello!</span></p></div>",
"prev_topic": "party at my houz",
"timestamp": 1530129134
}
],
"msg": "",
"result": "success"
}
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidMessageError'
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
/messages/flags:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_message_flags
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Add or remove flags in a list of messages.
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
`POST {{ api_url }}/v1/messages/flags`
For updating the `read` flag on common collections of messages, see also
the
[special endpoints for marking message as read in bulk](/api/mark-as-read-bulk).
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
parameters:
- name: messages
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
An array containing the IDs of the target messages.
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
schema:
type: array
items:
type: integer
example: [4, 8, 15]
required: true
- name: op
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether to `add` the flag or `remove` it.
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
schema:
type: string
enum:
- add
- remove
example: add
required: true
- name: flag
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The flag that should be added/removed.
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
schema:
type: string
example: read
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
messages:
type: array
items:
type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
An array with the IDs of the modified messages.
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
- example:
{
"msg": "",
"messages": [
4, 18, 15
],
"result": "success"
}
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
/messages/render:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: render_message
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Render a message to HTML.
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
`POST {{ api_url }}/v1/messages/render`
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
parameters:
api_docs: Add "Content" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "content" in components.
2020-04-19 11:46:51 +02:00
- $ref: '#/components/parameters/Content'
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
rendered:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The rendered HTML.
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
- example:
{
"msg": "",
"rendered": "<p><strong>foo</strong></p>",
"result": "success"
}
/messages/{message_id}/reactions:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: add_reaction
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Create markdown extension for rendering endpoint descriptions. Add function in openapi.py to access endpoint descriptions written in zulip.yaml. Use this function for creating a markdown extension for rendering endpoint descriptions written in zulip.yaml. We use this extension for a single endpoint to get test coverage.
2020-04-28 12:13:46 +02:00
Add an [emoji reaction](/help/emoji-reactions) to a message.
`POST {{ api_url }}/v1/messages/{message_id}/reactions`
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
parameters:
api_docs: Add "MessageId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "message_id" in components.
2020-04-20 16:46:14 +02:00
- $ref: '#/components/parameters/MessageId'
api_docs: Add "EmojiName" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_name" in components.
2020-04-21 22:24:18 +02:00
- $ref: '#/components/parameters/EmojiName'
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
required: true
api_docs: Add "EmojiCode" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_code" in components.
2020-04-24 03:02:15 +02:00
- $ref: '#/components/parameters/EmojiCode'
api_docs: Add "ReactionType" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "reaction_type" in components.
2020-04-21 22:29:35 +02:00
- $ref: '#/components/parameters/ReactionType'
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
responses:
'200':
openapi: Use response schema for describing simple success response. In zulip.yaml simple json success response which only contains 'msg' and 'result' properties has been described repeatedly in multiple endpoints. Instead, use SimpleSuccess template for such responses to increase code modularity and reusablility.
2020-03-29 15:55:14 +02:00
$ref: '#/components/responses/SimpleSuccess'
api: Document POST ../messages/{message_id}/reactions endpoint. This refactors add_reaction in python_examples.py to use the openapi_test_function decorator and validate result with validate_against_openapi_schema. Minor changes have been made to the OpenAPI format data for /messages/{message_id}/reactions endpoint. This also adds add-emoji.md to templates/zerver/api and adds add-emoji to rest-endpoints.md (templates/zerver/help/include).
2020-02-29 15:02:34 +01:00
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
- example:
{
api: Document POST ../messages/{message_id}/reactions endpoint. This refactors add_reaction in python_examples.py to use the openapi_test_function decorator and validate result with validate_against_openapi_schema. Minor changes have been made to the OpenAPI format data for /messages/{message_id}/reactions endpoint. This also adds add-emoji.md to templates/zerver/api and adds add-emoji to rest-endpoints.md (templates/zerver/help/include).
2020-02-29 15:02:34 +01:00
"result": "error",
"msg": "Invalid emoji code",
"code": "BAD_REQUEST"
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
}
api: Document POST ../messages/{message_id}/reactions endpoint. This refactors add_reaction in python_examples.py to use the openapi_test_function decorator and validate result with validate_against_openapi_schema. Minor changes have been made to the OpenAPI format data for /messages/{message_id}/reactions endpoint. This also adds add-emoji.md to templates/zerver/api and adds add-emoji to rest-endpoints.md (templates/zerver/help/include).
2020-02-29 15:02:34 +01:00
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: remove_reaction
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Remove an [emoji reaction](/help/emoji-reactions) from a message.
`DELETE {{ api_url }}/v1/messages/{message_id}/reactions`
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
parameters:
api_docs: Add "MessageId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "message_id" in components.
2020-04-20 16:46:14 +02:00
- $ref: '#/components/parameters/MessageId'
api_docs: Add "EmojiName" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_name" in components.
2020-04-21 22:24:18 +02:00
- $ref: '#/components/parameters/EmojiName'
api: Document DELETE ../messages/{message_id}/reactions endpoint. This refactors remove_reaction in python_examples.py to validate the result with validate_against_openapi_schema. Minor changes and some additions have been made to the OpenAPI format data for /messages/{message_id}/reactions endpoint.
2020-03-07 11:20:57 +01:00
required: false
api_docs: Add "EmojiCode" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_code" in components.
2020-04-24 03:02:15 +02:00
- $ref: '#/components/parameters/EmojiCode'
api_docs: Add "ReactionType" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "reaction_type" in components.
2020-04-21 22:29:35 +02:00
- $ref: '#/components/parameters/ReactionType'
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
responses:
'200':
openapi: Use response schema for describing simple success response. In zulip.yaml simple json success response which only contains 'msg' and 'result' properties has been described repeatedly in multiple endpoints. Instead, use SimpleSuccess template for such responses to increase code modularity and reusablility.
2020-03-29 15:55:14 +02:00
$ref: '#/components/responses/SimpleSuccess'
api: Document DELETE ../messages/{message_id}/reactions endpoint. This refactors remove_reaction in python_examples.py to validate the result with validate_against_openapi_schema. Minor changes and some additions have been made to the OpenAPI format data for /messages/{message_id}/reactions endpoint.
2020-03-07 11:20:57 +01:00
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
- example:
{
api: Document DELETE ../messages/{message_id}/reactions endpoint. This refactors remove_reaction in python_examples.py to validate the result with validate_against_openapi_schema. Minor changes and some additions have been made to the OpenAPI format data for /messages/{message_id}/reactions endpoint.
2020-03-07 11:20:57 +01:00
"result": "error",
"msg": "Invalid message(s)",
"code": "BAD_REQUEST"
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
}
api docs: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
/user_uploads:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: upload_file
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Upload a single file and get the corresponding URI.
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
`POST {{ api_url }}/v1/user_uploads`
Initially, only you will be able to access the link. To share the
uploaded file, you'll need to [send a message][send-message]
containing the resulting link. Users who can already access the link
can reshare it with other users by sending additional Zulip messages
containing the link.
[uploaded-files]: /help/manage-your-uploaded-files
[send-message]: /api/send-message
api docs: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
requestBody:
content:
multipart/form-data:
schema:
properties:
filename:
type: string
format: binary
docs: Add curl example to upload-file.
2019-10-16 13:11:07 +02:00
example: /path/to/file
api docs: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
uri:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The URI of the uploaded file.
api docs: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
- example:
{
"msg": "",
"result": "success",
"uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt"
}
upload: Support requesting a temporary unauthenticated URL. This is be useful for the mobile and desktop apps to hand an uploaded file off to the system browser so that it can render PDFs (Etc.). The S3 backend implementation is simple; for the local upload backend, we use Django's signing feature to simulate the same sort of 60-second lifetime token. Co-Author-By: Mateusz Mandera <mateusz.mandera@protonmail.com>
2020-04-08 00:27:24 +02:00
/user_uploads/{realm_id_str}/{filename}:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_file_temporary_url
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
upload: Support requesting a temporary unauthenticated URL. This is be useful for the mobile and desktop apps to hand an uploaded file off to the system browser so that it can render PDFs (Etc.). The S3 backend implementation is simple; for the local upload backend, we use Django's signing feature to simulate the same sort of 60-second lifetime token. Co-Author-By: Mateusz Mandera <mateusz.mandera@protonmail.com>
2020-04-08 00:27:24 +02:00
description: |
Get a temporary URL for access to the file that doesn't require authentication.
parameters:
- name: realm_id_str
in: path
description: |
The realm id.
schema:
type: integer
example: 1
required: True
- name: filename
in: path
description: |
Path to the URL.
schema:
type: string
example: 4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt
required: True
openapi: Fix minor error in zulip.yaml
2020-04-17 21:25:39 +02:00
responses:
'200':
upload: Support requesting a temporary unauthenticated URL. This is be useful for the mobile and desktop apps to hand an uploaded file off to the system browser so that it can render PDFs (Etc.). The S3 backend implementation is simple; for the local upload backend, we use Django's signing feature to simulate the same sort of 60-second lifetime token. Co-Author-By: Mateusz Mandera <mateusz.mandera@protonmail.com>
2020-04-08 00:27:24 +02:00
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
url:
type: string
description: |
A temporary URL that can be used to access the uploaded file
without Zulip's normal API authentication.
- example:
{
"msg": "",
"result": "success",
"url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55"
}
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
/users:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_users
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Retrieve details on all users in the organization. Optionally
includes values of [custom profile field](/help/add-custom-profile-fields).
`GET {{ api_url }}/v1/users`
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
parameters:
api_docs: Add "ClientGravatar" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "client_gravatar" in components.
2020-04-19 11:21:51 +02:00
- $ref: '#/components/parameters/ClientGravatar'
api_docs: Add IncludeCustomProfileFields component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "include_custom_profile_fields" in components.
2020-04-21 22:26:12 +02:00
- $ref: '#/components/parameters/IncludeCustomProfileFields'
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
members:
type: array
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of `user` objects, each containing details about a user in the
organization.
openapi: Pass validation of zulip.yaml on openapi-generator. The openapi-generator has an additional set of requirements for validation. Make changes in zulip.yaml accordingly.
2020-04-18 12:46:15 +02:00
items:
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
$ref: '#/components/schemas/User'
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
- example:
{
docs: Update the example for /users for custom profile fields. The previous example no longer gives a good enough idea of what the user can expect when the `include_custom_profile_fields` boolean parameter is set to true.
2019-10-25 20:36:17 +02:00
"msg": "",
"result": "success",
"members": [
{
"is_active": true,
"email": "AARON@zulip.com",
"is_admin": false,
users: Add is_owner field to user objects returned by get endpoints. This commit adds 'is_owner' field to the user object returned by '/users', 'users/{user_id}', and '/users/me' endpoints.
2020-06-01 21:47:18 +02:00
"is_owner": false,
docs: Update the example for /users for custom profile fields. The previous example no longer gives a good enough idea of what the user can expect when the `include_custom_profile_fields` boolean parameter is set to true.
2019-10-25 20:36:17 +02:00
"avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1",
"bot_type": null,
"timezone": "",
"is_bot": false,
"user_id": 7,
"profile_data": {},
"is_guest": false,
"date_joined": "2019-10-20T07:50:53.728864+00:00",
"full_name": "aaron"
},
{
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"full_name": "King Hamlet",
"is_guest": false,
"profile_data": {
"4": {
"value": "vim"
},
"2": {
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>"
},
"5": {
"value": "1900-1-1"
},
"7": {
"value": "[11]"
},
"6": {
"value": "https://blog.zulig.org"
},
"1": {
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>"
},
"8": {
"value": "zulipbot"
},
"3": {
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate"
}
},
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
users: Add is_owner field to user objects returned by get endpoints. This commit adds 'is_owner' field to the user object returned by '/users', 'users/{user_id}', and '/users/me' endpoints.
2020-06-01 21:47:18 +02:00
"is_owner": false,
docs: Update the example for /users for custom profile fields. The previous example no longer gives a good enough idea of what the user can expect when the `include_custom_profile_fields` boolean parameter is set to true.
2019-10-25 20:36:17 +02:00
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com"
},
{
"bot_owner_id": 11,
"is_guest": false,
"date_joined": "2019-10-20T12:52:17.862053+00:00",
"full_name": "Iago's Bot",
"email": "iago-bot@zulipdev.com",
"is_active": true,
"avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1",
"is_admin": false,
users: Add is_owner field to user objects returned by get endpoints. This commit adds 'is_owner' field to the user object returned by '/users', 'users/{user_id}', and '/users/me' endpoints.
2020-06-01 21:47:18 +02:00
"is_owner": false,
docs: Update the example for /users for custom profile fields. The previous example no longer gives a good enough idea of what the user can expect when the `include_custom_profile_fields` boolean parameter is set to true.
2019-10-25 20:36:17 +02:00
"user_id": 23,
"bot_type": 1,
"timezone": "",
"is_bot": true
}
]
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
}
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: create_user
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Create a new user account via the API.
`POST {{ api_url }}/v1/users`
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
parameters:
- name: email
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The email address of the new user.
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
docs: Make create-user use curl example system.
2019-10-11 14:58:24 +02:00
example: username@example.com
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
required: true
- name: password
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The password of the new user.
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
docs: Make create-user use curl example system.
2019-10-11 14:58:24 +02:00
example: abcd1234
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
required: true
- name: full_name
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The full name of the new user.
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
docs: Make create-user use curl example system.
2019-10-11 14:58:24 +02:00
example: New User
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
required: true
- name: short_name
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The short name of the new user. Not user-visible.
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
docs: Make create-user use curl example system.
2019-10-11 14:58:24 +02:00
example: newuser
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
"msg": "Email 'newbie@zulip.com' already in use",
"result": "error"
}
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
/users/{user_id}:
get:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: get_user
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Fetch details for a single user in the organization.
`GET {{ api_url }}/v1/users/{user_id}`
You can also fetch details on [all users in the organization](/api/get-all-users).
*This endpoint is new in Zulip Server 2.2.*
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
parameters:
api_docs: Add "UserId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "user_id" in components.
2020-04-21 21:44:21 +02:00
- $ref: '#/components/parameters/UserId'
api_docs: Add "ClientGravatar" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "client_gravatar" in components.
2020-04-19 11:21:51 +02:00
- $ref: '#/components/parameters/ClientGravatar'
api_docs: Add IncludeCustomProfileFields component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "include_custom_profile_fields" in components.
2020-04-21 22:26:12 +02:00
- $ref: '#/components/parameters/IncludeCustomProfileFields'
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
api: Refactor get_members_backend in zerver/views/users.py. This refactors get_members_backend to return user data of a single user in the form of a dictionary (earlier being a list with a single dictionary). This also refactors it to return the data with an appropriate key (inside a dictionary), "user" or "members", according to the type of data being returned. Tweaked by tabbott to use somewhat less opaque code and simple OpenAPI descriptions.
2020-03-08 21:13:11 +01:00
user:
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
$ref: '#/components/schemas/User'
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
- example:
{
"msg": "",
"result": "success",
api: Refactor get_members_backend in zerver/views/users.py. This refactors get_members_backend to return user data of a single user in the form of a dictionary (earlier being a list with a single dictionary). This also refactors it to return the data with an appropriate key (inside a dictionary), "user" or "members", according to the type of data being returned. Tweaked by tabbott to use somewhat less opaque code and simple OpenAPI descriptions.
2020-03-08 21:13:11 +01:00
"user": {
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"full_name": "King Hamlet",
"is_guest": false,
"profile_data": {
"4": {
"value": "vim"
},
"2": {
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>"
},
"5": {
"value": "1900-1-1"
},
"7": {
"value": "[11]"
},
"6": {
"value": "https://blog.zulig.org"
},
"1": {
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>"
},
"8": {
"value": "zulipbot"
},
"3": {
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate"
}
},
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
users: Add is_owner field to user objects returned by get endpoints. This commit adds 'is_owner' field to the user object returned by '/users', 'users/{user_id}', and '/users/me' endpoints.
2020-06-01 21:47:18 +02:00
"is_owner": false,
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com"
}
}
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_user
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Administrative endpoint to update the details of another user in the organization.
`PATCH {{ api_url }}/v1/users/{user_id}`
Supports everything an administrator can do to edit details of another
user's account, including editing full name,
[role](/help/roles-and-permissions), and [custom profile
fields](/help/add-custom-profile-fields).
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
parameters:
api_docs: Add "UserId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "user_id" in components.
2020-04-21 21:44:21 +02:00
- $ref: '#/components/parameters/UserId'
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
- name: full_name
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The user's full name.
openapi: Rectify wrong examples and schemas. Some examples mentioned in zulip.yaml did not match their schema. Change either the schema or the example so that all examples are valid with respect to their schemas.
2020-05-11 14:14:12 +02:00
content:
application/json:
schema:
type: string
example: NewName
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
required: false
users: Modify update user API endpoint to accept role as parameter. This commit changes the update user API endpoint to accept role as parameter instead of the bool parameters is_guest and is_admin. User role dropdown in user info modal is also modified to use "dropdown_options_widget". Modified by tabbott to document the API change.
2020-05-29 16:12:09 +02:00
- name: role
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
users: Modify update user API endpoint to accept role as parameter. This commit changes the update user API endpoint to accept role as parameter instead of the bool parameters is_guest and is_admin. User role dropdown in user info modal is also modified to use "dropdown_options_widget". Modified by tabbott to document the API change.
2020-05-29 16:12:09 +02:00
New [role](/help/roles-and-permissions) for the user. Supported roles include:
* Organization owner: 100
* Organization administrator: 200
* Member: 400
* Guest: 600
Only organization owners can add or remove the owner permission.
The owner permission cannot be removed from the only organization owner.
**Changes**: New in Zulip 2.2 (feature level 8), replacing the previous
pair of `is_admin` and `is_guest` boolean parameters.
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
schema:
users: Modify update user API endpoint to accept role as parameter. This commit changes the update user API endpoint to accept role as parameter instead of the bool parameters is_guest and is_admin. User role dropdown in user info modal is also modified to use "dropdown_options_widget". Modified by tabbott to document the API change.
2020-05-29 16:12:09 +02:00
type: integer
example: 400
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
required: false
- name: profile_data
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A dictionary containing the to be updated custom profile field data for the user.
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
schema:
type: array
items:
type: object
example: [
{
api docs: Redesign visuals for documenting arguments. The previous system for documenting arguments was very ugly if any of the examples or descriptions were wrong. After thinking about this for a while, I concluded the core problem was that a table was the wrong design element to use for API parameters, and we'd be much better off with individual card-type widgets instead. This rewrites the API arguments documentation implementation to use a basic sort of card-like system with some basic styling; I think the result is a lot more readable, and it's a lot more clear how we would add additional OpenAPI details (like parameter types) to the documentation.
2020-03-27 05:03:26 +01:00
"id": 4,
"value": "vim"
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
},
{
api docs: Redesign visuals for documenting arguments. The previous system for documenting arguments was very ugly if any of the examples or descriptions were wrong. After thinking about this for a while, I concluded the core problem was that a table was the wrong design element to use for API parameters, and we'd be much better off with individual card-type widgets instead. This rewrites the API arguments documentation implementation to use a basic sort of card-like system with some basic styling; I think the result is a lot more readable, and it's a lot more clear how we would add additional OpenAPI details (like parameter types) to the documentation.
2020-03-27 05:03:26 +01:00
"id": 5,
"value": "1909-04-05"
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
},
]
required: false
responses:
'200':
openapi: Use response schema for describing simple success response. In zulip.yaml simple json success response which only contains 'msg' and 'result' properties has been described repeatedly in multiple endpoints. Instead, use SimpleSuccess template for such responses to increase code modularity and reusablility.
2020-03-29 15:55:14 +02:00
$ref: '#/components/responses/SimpleSuccess'
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"result": "error",
"msg": "Guests cannot be organization administrators",
"code": "BAD_REQUEST"
}
delete:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: deactivate_user
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
[Deactivates a
user](https://zulipchat.com/help/deactivate-or-reactivate-a-user)
given their user ID.
`DELETE {{ api_url }}/v1/users/{user_id}`
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
parameters:
api_docs: Add "UserId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "user_id" in components.
2020-04-21 21:44:21 +02:00
- $ref: '#/components/parameters/UserId'
openapi: Add OpenAPI format data for /users/{user_id} endpoint. This adds the OpenAPI format data for /users/{user_id} endpoint and also removes 'users/{user_id}' from 'pending_endpoints' in zerver/tests/test_openapi.py .
2020-02-14 21:22:52 +01:00
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- example:
{
"msg": "",
"result": "success",
}
'400':
description: Bad Request
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
"msg": "Cannot deactivate the only organization administrator",
"result": "error"
}
openapi: Add OpenAPI data for /users/{user_id}/reactivate.
2020-05-16 21:51:26 +02:00
/users/{user_id}/reactivate:
post:
openapi: Add tests for checking presence of various attributes. The swagger validator is a basic tool to check whether our openapi specification file follows the basic syntax. But to ensure that our zulip.yaml file is not only syntactically compatible but also describes our API well, we need to add custom tests. This commit currently checks whether each endpoint has an `operationId` and a valid tag. It also makes it easier to check for custom rules in the future.
2020-05-20 19:53:41 +02:00
operationId: reactivate_user
tags: ["users"]
openapi: Add OpenAPI data for /users/{user_id}/reactivate.
2020-05-16 21:51:26 +02:00
description: |
[Reactivates a
user](https://zulipchat.com/help/deactivate-or-reactivate-a-user)
given their user ID.
`POST {{ api_url }}/v1/users/{user_id}/reactivate`
parameters:
- $ref: '#/components/parameters/UserId'
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- example:
{
"msg": "",
"result": "success",
}
api docs: Document GET /users/<email>/presence. Tweaked by tabbott to describe more clearly what this is for.
2018-08-07 17:52:03 +02:00
/users/{email}/presence:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_user_presence
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Get the presence status for a specific user.
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
This endpoint is most useful for embedding data about a user's
presence status in other sites (E.g. an employee directory). Full
Zulip clients like mobile/desktop apps will want to use the main
presence endpoint, which returns data for all active users in the
organization, instead.
`GET {{ api_url }}/v1/users/{email}/presence`
See
[Zulip's developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/presence.html)
for details on the data model for presence in Zulip.
api docs: Document GET /users/<email>/presence. Tweaked by tabbott to describe more clearly what this is for.
2018-08-07 17:52:03 +02:00
parameters:
- name: email
in: path
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The email address of the user whose presence you want to fetch.
api docs: Document GET /users/<email>/presence. Tweaked by tabbott to describe more clearly what this is for.
2018-08-07 17:52:03 +02:00
schema:
type: string
example: iago@zulip.com
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
presence:
type: object
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
An object containing the presence details for every client the user has
logged into.
openapi_responses: Fix get_user_presence.
2020-05-27 14:01:20 +02:00
additionalProperties:
type: object
properties:
timestamp:
type: integer
description: |
when this update was received; if the timestamp
is more than a few minutes in the past, the user is offline.
status:
type: string
description: |
either `active` or `idle`: whether the user had
recently interacted with Zulip at the time in the timestamp
(this distinguishes orange vs. green dots in the Zulip web
UI; orange/idle means we don't know whether the user is
actually at their computer or just left the Zulip app open
on their desktop).
description: |
`{client_name}` or `aggregated`: the keys for these objects are
the names of the different clients where this user is logged in,
like `website`, `ZulipDesktop`, `ZulipTerminal`, or
`ZulipMobile`. There is also an `aggregated` key, which matches
the contents of the object that has been updated most
recently. For most applications, you'll just want to look at the
`aggregated` key.
api docs: Document GET /users/<email>/presence. Tweaked by tabbott to describe more clearly what this is for.
2018-08-07 17:52:03 +02:00
- example:
{
"presence": {
"website": {
"timestamp": 1532697622,
"status": "active",
},
"ZulipMobile": {
"timestamp": 1522687421,
"status": "active",
},
"aggregated": {
"timestamp": 1532697622,
"status": "active",
}
},
"result": "success",
"msg": ""
}
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
/users/me:
get:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: get_own_user
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Get basic data about the user/bot that requests this endpoint.
`GET {{ api_url }}/v1/users/me`
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
api: Add avatar URL to the GET /profile endpoint. This endpoint is legacy in a lot of ways, but it seems reasonable that it should have these data.
2019-09-27 21:07:03 +02:00
avatar_url:
type: string
docs: Update API documention to note changes in Zulip 2.1.0.
2020-03-27 02:02:20 +01:00
description: |
URL for the user's avatar.
**Changes**: New in Zulip 2.1.0.
api: Add avatar URL to the GET /profile endpoint. This endpoint is legacy in a lot of ways, but it seems reasonable that it should have these data.
2019-09-27 21:07:03 +02:00
example: "x"
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
client_id:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
NA
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
example: "74c768b081076fdb3c4326256c17467e"
email:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Email of the requesting user.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
example: "iago@zulip.com"
full_name:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Full name of the requesting user.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
example: "Iago"
is_admin:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A boolean indicating if the requesting user is an admin.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
example: true
users: Add is_owner field to user objects returned by get endpoints. This commit adds 'is_owner' field to the user object returned by '/users', 'users/{user_id}', and '/users/me' endpoints.
2020-06-01 21:47:18 +02:00
is_owner:
type: boolean
description: |
A boolean indicating if the requesting user is
an organization owner.
**Changes**: New in Zulip 2.2 (feature level 8).
example: false
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
is_bot:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A boolean indicating if the requesting user is a bot.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
example: false
max_message_id:
type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi_responses: Fix get_own_user.
2020-05-26 13:30:40 +02:00
The integer ID of the last message received by your account.
**Deprecated**. We plan to remove this in favor of recommending
using `GET /messages` with `anchor="newest"`.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
example: 30
pointer:
type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi_responses: Fix get_own_user.
2020-05-26 13:30:40 +02:00
The integer ID of the message that the pointer is currently on.
**Deprecated**. We plan to remove the `pointer` as a concept in Zulip.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
example: -1
short_name:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Short name of the requesting user.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
example: "iago"
user_id:
type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The user's ID.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
example: 1
users: Send custom profile fields with the /profile endpoint.
2019-10-25 20:28:53 +02:00
profile_data:
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
$ref: '#/components/schemas/profile_data'
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
- example:
{
api: Add avatar URL to the GET /profile endpoint. This endpoint is legacy in a lot of ways, but it seems reasonable that it should have these data.
2019-09-27 21:07:03 +02:00
"avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1",
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
"client_id": "74c768b081076fdb3c4326256c17467e",
"email": "iago@zulip.com",
"full_name": "Iago",
"is_admin": true,
users: Add is_owner field to user objects returned by get endpoints. This commit adds 'is_owner' field to the user object returned by '/users', 'users/{user_id}', and '/users/me' endpoints.
2020-06-01 21:47:18 +02:00
"is_owner": false,
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
"is_bot": false,
"max_message_id": 30,
"msg": "",
"pointer": -1,
"result": "success",
"short_name": "iago",
users: Send custom profile fields with the /profile endpoint.
2019-10-25 20:28:53 +02:00
"user_id": 5,
"profile_data": {
"5": {
"value": "2000-1-1"
},
"4": {
"value": "emacs"
},
"7": {
"value": "[10]"
},
"1": {
"value": "+1-234-567-8901",
"rendered_value": "<p>+1-234-567-8901</p>"
},
"2": {
"rendered_value": "<p>Betrayer of Othello.</p>",
"value": "Betrayer of Othello."
},
"8": {
"value": "zulip"
},
"3": {
"value": "Apples",
"rendered_value": "<p>Apples</p>"
},
"6": {
"value": "https://zulip.readthedocs.io/en/latest/"
}
}
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
}
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: deactivate_my_account
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Delete the requesting user from the realm.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
responses:
'200':
description: Bad Request
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- example:
{
"msg": "",
"result": "success",
}
'400':
description: Bad Request
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
"msg": "Cannot deactivate the only organization administrator",
"result": "error"
}
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
/users/me/{stream_id}/topics:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_stream_topics
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Get all the topics in a specific stream
`GET {{ api_url }}/v1/users/me/{stream_id}/topics`
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
parameters:
api_docs: Add "StreamIdInPath" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in path) in components.
2020-04-19 10:30:30 +02:00
- $ref: '#/components/parameters/StreamIdInPath'
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
topics:
type: array
openapi_responses: Fix get_stream_topics.
2020-05-26 13:23:39 +02:00
description: |
An array of `topic` objects.
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
items:
type: object
properties:
max_id:
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi_responses: Fix get_stream_topics.
2020-05-26 13:23:39 +02:00
The message ID of the last message sent to this topic.
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
type: integer
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
name:
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The name of the topic.
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
type: string
- example:
{
api docs: Fix indentation.
2018-06-06 18:17:58 +02:00
"msg": "",
"result": "success",
"topics": [
{
"max_id": 26,
"name": "Denmark3"
},
{
"max_id": 23,
"name": "Denmark1"
},
{
"max_id": 6,
"name": "Denmark2"
}
]
}
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
"result": "error"
}
/users/me/subscriptions:
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
get:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: get_subscriptions
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Get all streams that the user is subscribed to.
`GET {{ api_url }}/v1/users/me/subscriptions`
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
# operationId can be used to record which view function
# corresponds to an endpoint. TODO: Add these for more
# endpoints, and perhaps use this to provide links to implementations.
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
parameters:
api_docs: Add "IncludeSubscribers" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "IncludeSubscribers" in components.
2020-04-21 22:14:11 +02:00
- $ref: '#/components/parameters/IncludeSubscribers'
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
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
# TODO: Is this the best way to declare required elements in 200 responses?
- required:
- subscriptions
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
- properties:
subscriptions:
type: array
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
description: |
A list of dictionaries where each dictionary contains
information about one of the subscribed streams.
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
items:
type: object
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
properties:
stream_id:
type: integer
description: |
The unique ID of a stream.
name:
type: string
description: |
The name of a stream.
description:
type: string
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
The short description of a stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
rendered_description:
type: string
description: |
A short description of a stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
invite_only:
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
type: boolean
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
Specifies whether the stream is private or not.
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
Only people who have been invited can access a private stream.
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
# TODO: This subscribers item should probably be declared optional more
# explicitly in the OpenAPI format?
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
subscribers:
type: array
items:
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
type: integer
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
A list of user IDs of users who are also subscribed
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
to a given stream. Included only if `include_subscribers` is `true`.
desktop_notifications:
type: boolean
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
nullable: true
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
description: |
A boolean specifying whether desktop notifications
are enabled for the given stream.
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_desktop_notifications, for
this stream.
email_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether email notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_email_notifications, for
this stream.
wildcard_mentions_notify:
type: boolean
nullable: true
description: |
A boolean specifying whether wildcard mentions
trigger notifications as though they were personal
mentions in this stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, wildcard_mentions_notify, for
this stream.
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
push_notifications:
type: boolean
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
nullable: true
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
description: |
A boolean specifying whether push notifications
are enabled for the given stream.
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_push_notifications, for
this stream.
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
audible_notifications:
type: boolean
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
nullable: true
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
description: |
A boolean specifying whether audible notifications
are enabled for the given stream.
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_audible_notifications, for
this stream.
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
pin_to_top:
type: boolean
description: |
A boolean specifying whether the given stream has been pinned
to the top.
email_address:
type: string
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
Email address of the given stream, used for
[sending emails to the stream](/help/message-a-stream-by-email).
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
is_muted:
type: boolean
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
Whether the user has muted the stream. Muted streams do
not count towards your total unread count and do not show up in
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
`All messages` view (previously known as `Home` view).
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
**Changes**: Prior to Zulip 2.1, this feature was
represented by the more confusingly named `in_home_view` (with the
opposite value, `in_home_view=!is_muted`).
in_home_view:
type: boolean
description: |
Legacy property for if the given stream is muted, with inverted meeting.
**Deprecated**; clients should use is_muted where available.
is_old_stream:
type: boolean
description: |
Whether the stream is old enough to have data in
`stream_weekly_traffic`.
**Deprecated**: To me removed. Clients should simply check
whether stream_weekly_traffic is null.
is_announcement_only:
type: boolean
description: |
Whether only organization administrators can post to the stream.
**Changes**: Deprecated in Zulip 2.2 (feature level 1), use
`stream_post_policy` instead.
is_web_public:
type: boolean
description: |
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
openapi_responses: Fix list_subscriptions.
2020-05-27 17:20:05 +02:00
color:
type: string
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
The user's personal color for the stream.
stream_post_policy:
type: integer
description: |
Policy for which users can post messages to the stream.
* 1 => Any user can post.
* 2 => Only administrators can post.
* 3 => Only new members can post.
**Changes**: New in Zulip 2.2, replacing the previous
`is_announcement_only` boolean.
history_public_to_subscribers:
type: boolean
description: |
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
first_message_id:
type: integer
description: |
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
stream_weekly_traffic:
type: integer
nullable: true
description: |
The average number of messages sent to the stream in recent weeks,
rounded to the nearest integer.
Null means the stream was recently created and there is
insufficient data to estimate the average traffic.
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
- example:
{
"msg": "",
"result": "success",
"subscriptions": [
{
"audible_notifications": true,
"color": "#e79ab5",
"description": "A Scandinavian country",
"desktop_notifications": true,
"email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981",
docs: Update API documention to note changes in Zulip 2.1.0.
2020-03-27 02:02:20 +01:00
"is_muted": false,
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
"invite_only": false,
"name": "Denmark",
"pin_to_top": false,
"push_notifications": false,
"stream_id": 1,
"subscribers": [
"ZOE@zulip.com",
"hamlet@zulip.com",
"iago@zulip.com",
"othello@zulip.com",
"prospero@zulip.com"
]
},
{
"audible_notifications": true,
"color": "#e79ab5",
"description": "Located in the United Kingdom",
"desktop_notifications": true,
"email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981",
docs: Update API documention to note changes in Zulip 2.1.0.
2020-03-27 02:02:20 +01:00
"is_muted": false,
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
"invite_only": false,
"name": "Scotland",
"pin_to_top": false,
"push_notifications": false,
"stream_id": 3,
"subscribers": [
"ZOE@zulip.com",
"iago@zulip.com",
"othello@zulip.com",
"prospero@zulip.com"
]
}
]
}
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: subscribe
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Subscribe one or more users to one or more 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
`POST {{ api_url }}/v1/users/me/subscriptions`
If any of the specified streams do not exist, they are automatically
created, and configured using the `invite_only` setting specified in
the arguments (see below).
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
parameters:
- name: subscriptions
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
"A list of dictionaries containing the the key `name` and value
specifying the name of the stream to subscribe. If the stream does not
exist a new stream is created. The description of the stream created can
be specified by setting the dictionary key `description` with an
appropriate value.
openapi: Improve description of subscriptions in /users/me/subscriptions.
2019-10-10 10:55:48 +02:00
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
**Note**: This argument is called `streams` and not `subscriptions`
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
in our Python API."
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: array
api docs: Specify array types.
2018-06-21 02:18:05 +02:00
items:
type: object
api: Document support for setting stream description on creation. This makes clear how to set the stream description when making a new stream. Fixes #11372.
2019-01-29 20:20:58 +01:00
example: [{"name": "Verona", "description": "Italian City"}]
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
required: true
- name: invite_only
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A boolean specifying whether the streams specified in `subscriptions`
are invite-only or not.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
schema:
type: boolean
default: false
example: true
api_docs: Add "Principals" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "principals" in components.
2020-04-21 22:27:56 +02:00
- $ref: '#/components/parameters/Principals'
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
- name: authorization_errors_fatal
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
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. When `True`, 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.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
schema:
type: boolean
default: true
example: false
api_docs: Add HistoryPublicToSubscribers component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "history_public_to_subscribers" in components.
2020-04-21 21:56:47 +02:00
- $ref: '#/components/parameters/HistoryPublicToSubscribers'
api_docs: Add "StreamPostPolicy" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_post_policy" in components.
2020-04-21 21:53:33 +02:00
- $ref: '#/components/parameters/StreamPostPolicy'
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
- name: announce
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
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.
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
schema:
type: boolean
example: true
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
responses:
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
content:
application/json:
schema:
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
oneOf:
- allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {
"iago@zulip.com": [
"new stream"
]
}
}
- allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {
"newbie@zulip.com": [
"new stream"
]
},
"msg": "",
"result": "success",
"subscribed": {}
}
'400':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
content:
application/json:
schema:
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
oneOf:
- allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"msg": "Unable to access stream (private_stream).",
"result": "error"
}
- allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {},
"unauthorized": [
"private_stream"
]
}
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
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_subscriptions
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Update which streams you are are subscribed to.
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
parameters:
- name: delete
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of stream names to unsubscribe from.
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
schema:
type: array
items:
type: string
example: ['Verona', 'Denmark']
required: false
- name: add
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of objects describing which streams to subscribe to, optionally
including per-user subscription parameters (e.g. color) and if the
stream is to be created, its description.
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
schema:
type: array
items:
type: object
openapi: Fix some errors caught by online editor. This fixes several values that had invalid types recorded.
2019-07-31 01:36:50 +02:00
properties:
name:
type: string
color:
type: string
description:
type: string
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
example:
[
{
"name": "Verona"
},
{
"name": "Denmark",
"color": "#e79ab5",
"description": "A Scandinavian country",
}
]
required: false
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
- required:
- subscribed
- not_subscribed
- already_subscribed
- removed
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
- properties:
subscribed:
type: object
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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.
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
already_subscribed:
type: object
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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.
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
not_removed:
type: array
items:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of the names of streams that the user
is already unsubscribed from, and hence
doesn't need to be unsubscribed.
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
removed:
type: array
items:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of the names of streams which were unsubscribed
from as a result of the query.
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
- example:
{
"msg": "",
"subscribed": {},
"already_subscribed": {"iago@zulip.com":["Verona"]},
"not_removed": [],
"removed": [
"new stream"
],
"result": "success"
}
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: unsubscribe
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Unsubscribe yourself or other users from one or more 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
`DELETE {{ api_url }}/v1/users/me/subscriptions`
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
parameters:
- name: subscriptions
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of stream names to unsubscribe from. This argument is called
`streams` in our Python API.
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
schema:
type: array
items:
type: string
example: ['Verona', 'Denmark']
required: true
api_docs: Add "Principals" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "principals" in components.
2020-04-21 22:27:56 +02:00
- $ref: '#/components/parameters/Principals'
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
Rename `not_subscribed key` to `not_removed` in users/me/subscriptions. Rename `not_subscibed_key` to `not_removed` in `users/me/subscriptions` DELETE response. Fixes #13277.
2019-10-13 05:30:34 +02:00
not_removed:
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
type: array
items:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of the names of streams that the user is already unsubscribed
from, and hence doesn't need to be unsubscribed.
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
removed:
type: array
items:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of the names of streams which were unsubscribed from as a result
of the query.
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
- example:
{
"msg": "",
Rename `not_subscribed key` to `not_removed` in users/me/subscriptions. Rename `not_subscibed_key` to `not_removed` in `users/me/subscriptions` DELETE response. Fixes #13277.
2019-10-13 05:30:34 +02:00
"not_removed": [],
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
"removed": [
"new stream"
],
"result": "success"
}
'400':
description: Bad request.
content:
application/json:
schema:
api docs: Create the NonExistingStreamError schema definition.
2018-06-21 02:25:29 +02:00
$ref: '#/components/schemas/NonExistingStreamError'
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
/users/me/subscriptions/muted_topics:
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: mute_topic
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
This endpoint mutes/unmutes a topic within a stream that the current
user is subscribed to. Muted topics are displayed faded in the Zulip
UI, and are not included in the user's unread count totals.
`PATCH {{ api_url }}/v1/users/me/subscriptions/muted_topics`
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
parameters:
api_docs: Add "Stream" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream" in components.
2020-04-18 17:59:13 +02:00
- $ref: '#/components/parameters/Stream'
tests: Remove /users/me/subscriptions/muted_topics from buggy endpoints. Even though required attribute of stream and stream_id params is marked false in openapi specification, the API expects atleast one of the params to be set. There is no way to specify relationships like this openapi and they dont seem to have any plan to implement this in future. https://github.com/OAI/OpenAPI-Specification/issues/256
2019-10-07 10:46:04 +02:00
required: false
api_docs: Add "StreamIdInQuery" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in query) in components.
2020-04-19 10:01:44 +02:00
- $ref: '#/components/parameters/StreamIdInQuery'
tests: Remove /users/me/subscriptions/muted_topics from buggy endpoints. Even though required attribute of stream and stream_id params is marked false in openapi specification, the API expects atleast one of the params to be set. There is no way to specify relationships like this openapi and they dont seem to have any plan to implement this in future. https://github.com/OAI/OpenAPI-Specification/issues/256
2019-10-07 10:46:04 +02:00
required: false
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
- name: topic
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The topic to (un)mute. Note that the request will succeed regardless of
whether any messages have been sent to the specified topic.
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
schema:
type: string
example: dinner
required: true
- name: op
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether to mute (`add`) or unmute (`remove`) the provided topic.
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
schema:
type: string
enum:
- add
- remove
example: add
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
'400':
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
description: Bad request.
content:
application/json:
schema:
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
oneOf:
- allOf:
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
- $ref: '#/components/schemas/JsonError'
- example:
{
"msg": "Topic already muted",
"result": "error"
}
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
- allOf:
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
- $ref: '#/components/schemas/JsonError'
- example:
{
muting: Correct agrammatical error message. The error message displayed when unmuting a topic that wasn't previously muted wasn't properly formulated.
2018-08-27 22:13:56 +02:00
"msg": "Topic is not muted",
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
"result": "error"
}
openapi: Standardize URL format to use {var_name} syntax. The previous code for the validator test was fairly messy due to checking for both formats of the openapi url, one with <variable_name> and the other with {variable_name}. To eliminate this, we have standardized the format and restricted it to {variable_name} as per the official format at: https://swagger.io/docs/specification/describing-parameters.
2019-07-11 12:45:26 +02:00
/realm/emoji/{emoji_name}:
api docs: Document the custom emoji upload endpoint. Tweaked by tabbott to fix some English phrasing and make the file pointer thing require less Python knowledge. Fixes: #10746.
2018-12-12 19:49:14 +01:00
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: upload_custom_emoji
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
This endpoint is used to upload a custom emoji for use in the user's
organization. Access to this endpoint depends on the
[organization's configuration](https://zulipchat.com/help/only-allow-admins-to-add-emoji).
`POST {{ api_url }}/v1/realm/emoji/{emoji_name}`
openapi: Add regex-to-openapi url pattern matching in the test. With this, the automated validation test will now be able to work with URL patterns containing regular expressions.
2019-07-04 18:12:53 +02:00
parameters:
- name: emoji_name
openapi: Fix some errors caught by online editor. This fixes several values that had invalid types recorded.
2019-07-31 01:36:50 +02:00
required: true
openapi: Add regex-to-openapi url pattern matching in the test. With this, the automated validation test will now be able to work with URL patterns containing regular expressions.
2019-07-04 18:12:53 +02:00
in: path
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The name that should be associated with the uploaded emoji image/gif.
openapi: Add regex-to-openapi url pattern matching in the test. With this, the automated validation test will now be able to work with URL patterns containing regular expressions.
2019-07-04 18:12:53 +02:00
schema:
type: string
api docs: Document the custom emoji upload endpoint. Tweaked by tabbott to fix some English phrasing and make the file pointer thing require less Python knowledge. Fixes: #10746.
2018-12-12 19:49:14 +01:00
requestBody:
content:
multipart/form-data:
schema:
properties:
filename:
type: string
format: binary
docs: Make upload-custom-emoji use curl example system.
2019-10-16 13:06:31 +02:00
example: /path/to/img.png
api docs: Document the custom emoji upload endpoint. Tweaked by tabbott to fix some English phrasing and make the file pointer thing require less Python knowledge. Fixes: #10746.
2018-12-12 19:49:14 +01:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
openapi: Add regex-to-openapi url pattern matching in the test. With this, the automated validation test will now be able to work with URL patterns containing regular expressions.
2019-07-04 18:12:53 +02:00
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
/realm/emoji:
get:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: get_custom_emoji
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Get all the custom emoji in the user's organization.
`GET {{ api_url }}/v1/realm/emoji`
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
emoji:
type: object
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
An object that contains `emoji` objects, each identified with their
emoji ID as the key.
openapi_responses: Improve response validation tests. Currently, `validate_against_openapi_schema` checks only the top level of the response dictionary. Improve it so that it can validate objects and arrays at all levels. Also edit zulip.yaml accordingly. And for new response keys which were not defined before add VERY basic documentation.
2020-06-02 18:04:03 +02:00
additionalProperties:
type: object
description: |
`{emoji_id}`: Object containing details about the emoji with
the specified ID. It has the following properties:
properties:
id:
type: string
description: |
The ID for this emoji, same as the object's key.
name:
type: string
description: |
The user-friendly name for this emoji. Users in the organization
can use this emoji by writing this name between colons (`:name :`).
source_url:
type: string
description: |
The path relative to the organization's URL where the
emoji's image can be found.
deactivated:
type: boolean
description: |
Whether the emoji has been deactivated or not.
author_id:
type: integer
nullable: true
description: |
The user ID of the user who uploaded the custom emoji.
Will be null if the uploader is unknown.
**Changes**: New in Zulip 2.2 (feature level 7). Previously
was accessible via and `author` object with an `id` field.
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
- example:
{
"result": "success",
"msg": "",
"emoji": {
"1": {
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/1/emoji/images/1.png",
"deactivated": false,
api: Simplify format of realm_emoji author data. There's no reason to send data beyond the user `id` of the uploader, and reason not to, as the previous model was both awkward when `author=None` and resulted in unecessary parsing complexity for clients. Modified by tabbott to add the frontend changes and API documentation. Fixes #15115.
2020-05-29 11:11:48 +02:00
"author_id": 5
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
}
}
}
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
/users/me/subscriptions/properties:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_subscription_settings
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
This endpoint is used to update the user's personal settings for the
streams they are subscribed to, including muting, color, pinning, and
per-stream notification settings.
`POST {{ api_url }}/v1/users/me/subscriptions/properties`
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
parameters:
- name: subscription_data
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of objects that describe the changes that should be applied in
each subscription. Each object represents a subscription, and must have
a `stream_id` key that identifies the stream, as well as the `property`
being modified and its new `value`.
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
schema:
type: array
items:
type: object
docs: Make update-subscription-properties use curl example system.
2019-10-10 11:06:47 +02:00
example: [{"stream_id": 1, "property": "pin_to_top", "value": true}, {"stream_id": 3, "property": "color", "value": '#f00f00'}]
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
subscription_data:
type: array
items:
type: object
openapi_responses: Fix update_subscription_settings.
2020-05-25 17:03:02 +02:00
properties:
color:
type: string
description: |
The hex value of the user's personal display color for the stream.
is_muted:
type: boolean
description: |
Whether the stream is [muted](/help/mute-a-stream).
**Changes**: Prior to Zulip 2.1, this feature was
represented by the more confusingly named `in_home_view` (with the
opposite value, `in_home_view=!is_muted`); for
backwards-compatibility, modern Zulip still accepts that value.
pin_to_top:
type: boolean
description: |
Whether to pin the stream at the top of the stream list.
desktop_notifications:
type: boolean
description: |
Whether to show desktop notifications for all messages sent to the stream.
audible_notifications:
type: boolean
description: |
Whether to play a sound notification for all messages sent to the stream.
push_notifications:
type: boolean
description: |
Whether to trigger a mobile push notification for all messages sent to the stream.
email_notifications:
type: boolean
description: |
Whether to trigger an email notification for all messages sent to the stream.
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The same `subscription_data` object sent by the client for the request.
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
- example:
{
"subscription_data": [
{
"property": "pin_to_top",
"value": true,
"stream_id": 1
},
{
"property": "color",
"value": 'f00',
"stream_id": 3
}
],
"result": "success",
"msg": ""
}
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
/realm/filters:
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
get:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: get_linkifiers
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
List all of an organization's configured
[linkifiers](/help/add-a-custom-linkification-filter), regular
expression patterns that are automatically linkified when they appear
in messages and topics.
`GET {{ api_url }}/v1/realm/filters`
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
filters:
type: array
items:
type: array
items:
openapi: Fix some errors caught by online editor. This fixes several values that had invalid types recorded.
2019-07-31 01:36:50 +02:00
oneOf:
- type: string
- type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
An array of tuples, each representing one of
the linkifiers set up in the
organization. Each of these tuples contain the
pattern, the formatted URL and the filter's
ID, in that order. See the [Create
linkifiers](/api/add-linkifiers) article for
details on what each field means.
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
- example:
{
"msg": "",
"filters": [
[
"#(?P<id>[0-9]+)",
"https://github.com/zulip/zulip/issues/%(id)s",
1
]
],
"result": "success"
}
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
post:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: add_linkifier
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Configure [linkifiers](/help/add-a-custom-linkification-filter),
regular expression patterns that are automatically linkified when they
appear in messages and topics.
`POST {{ api_url }}/v1/realm/filters`
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
parameters:
- name: pattern
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The [Python regular
expression](https://docs.python.org/3/howto/regex.html) that should
trigger the linkifier.
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
schema:
type: string
example: '#(?P<id>[0-9]+)'
required: true
- name: url_format_string
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The URL used for the link. If you used named groups for the `pattern`,
you can insert their content here with
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
`%(name_of_the_capturing_group)s`.
schema:
type: string
example: https://github.com/zulip/zulip/issues/%(id)s
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
id:
type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The numeric ID assigned to this filter.
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
- example:
{
"id": 42,
"result": "success",
"msg": ""
}
openapi: Standardize URL format to use {var_name} syntax. The previous code for the validator test was fairly messy due to checking for both formats of the openapi url, one with <variable_name> and the other with {variable_name}. To eliminate this, we have standardized the format and restricted it to {variable_name} as per the official format at: https://swagger.io/docs/specification/describing-parameters.
2019-07-11 12:45:26 +02:00
/realm/filters/{filter_id}:
api docs: Document DELETE /realm/filters/<filter_id>.
2018-08-14 03:20:39 +02:00
delete:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: remove_linkifier
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Remove [linkifiers](/help/add-a-custom-linkification-filter), regular
expression patterns that are automatically linkified when they appear
in messages and topics.
`DELETE {{ api_url }}/v1/realm/filters/{filter_id}`
api docs: Document DELETE /realm/filters/<filter_id>.
2018-08-14 03:20:39 +02:00
parameters:
- name: filter_id
in: path
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The ID of the filter that you want to remove.
api docs: Document DELETE /realm/filters/<filter_id>.
2018-08-14 03:20:39 +02:00
schema:
type: integer
example: 42
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
/register:
post:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: register_queue
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
This powerful endpoint can be used to register a Zulip "event queue"
(subscribed to certain types of "events", or updates to the messages and
other Zulip data the current user has access to), as well as to fetch
the current state of that data.
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
parameters:
- name: apply_markdown
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Set to `true` if you would like the content to be rendered in HTML
format (otherwise the API will return the raw text that the user
entered)
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
example: true
api_docs: Add "ClientGravatar" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "client_gravatar" in components.
2020-04-19 11:21:51 +02:00
- $ref: '#/components/parameters/ClientGravatar'
presence: Add slim_presence flag. This flag affects page_params and the payload you get back from POSTs to this url: users/me/presence The flag does not yet affect the presence events that get sent to a client.
2020-02-02 17:29:05 +01:00
- name: slim_presence
in: query
docs: Document changes in the API made since Zulip 2.1.x. This is important documentation for anyone working on writing clients for the Zulip APIs that wants to support older releases.
2020-03-27 01:45:03 +01:00
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
Setting this to `true` will make presence dictionaries be keyed by
user_id instead of email.
docs: Document changes in the API made since Zulip 2.1.x. This is important documentation for anyone working on writing clients for the Zulip APIs that wants to support older releases.
2020-03-27 01:45:03 +01:00
api docs: Add an API changelog page. I imagine this can be improved in various ways, but I've initialized this with all the **Changes** entries recorded in either zulip.yaml or the rest of the API documentation, and I expect we'll be able to iterate on this effectively. It'll also be useful as a record of changes that we should remember to document the API documentation as we document more endpoints that currently don't discuss these issues. While working on this, I fixed various issues where feature levels could be mentioned or endpoints didn't properly document changes.
2020-04-29 05:55:42 +02:00
**Changes**: New in Zulip 2.2 (Unstable with no feature level yet).
presence: Add slim_presence flag. This flag affects page_params and the payload you get back from POSTs to this url: users/me/presence The flag does not yet affect the presence events that get sent to a client.
2020-02-02 17:29:05 +01:00
schema:
type: boolean
default: false
example: true
api_docs: Add "event_types" common component. To facilitate re-use of the same parameters in other paths. this commit store the content of the parameter "event_types" in components.
2020-04-15 08:24:00 +02:00
- $ref: '#/components/parameters/Event_types'
openapi: Fix event_types param example in /register POST endpoint.
2019-10-14 12:09:35 +02:00
example: ['message']
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
- name: all_public_streams
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Set to `True` if you would like to receive events that occur within all
public streams.
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
example: true
api_docs: Add "IncludeSubscribers" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "IncludeSubscribers" in components.
2020-04-21 22:14:11 +02:00
- $ref: '#/components/parameters/IncludeSubscribers'
docs: Update API documention to note changes in Zulip 2.1.0.
2020-03-27 02:02:20 +01:00
- name: client_capabilities
in: query
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
Dictionary containing details on features the client supports that are
relevant to the format of responses sent by the server.
docs: Update API documention to note changes in Zulip 2.1.0.
2020-03-27 02:02:20 +01:00
* `notification_settings_null`: Boolean for whether the
client can handle the current API with null values for
stream-level notification settings (which means the stream
is not customized and should inherit the user's global
notification settings for stream messages). New in Zulip
2.1.0; in earlier Zulip releases, stream-level
notification settings were simple booleans.
schema:
type: object
tests: Fix CI apocalypse perpetrated by previous commit. Signed-off-by: Anders Kaseorg <anders@zulipchat.com>
2020-03-27 04:53:11 +01:00
example:
{
"notification_settings_null": true
}
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
- name: fetch_event_types
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Same as the `event_types` argument except that the values in
`fetch_event_types` are used to fetch initial data. If
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
`fetch_event_types` is not provided, `event_types` is used and if
`event_types` is not provided, this argument defaults to `None`.
schema:
api: Fix OpenAPI type declarations for events_register. A few fields that are actually arrays were incorrectly declared as strings.
2019-07-24 01:33:57 +02:00
type: array
openapi: Fix some errors caught by online editor. This fixes several values that had invalid types recorded.
2019-07-31 01:36:50 +02:00
items:
type: string
openapi: Fix fetch_event_types param example in /register POST endpoint.
2019-10-14 12:09:56 +02:00
example: ['message']
api_docs: Add "Narrow" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "narrow" in components.
2020-04-18 10:13:13 +02:00
- $ref: '#/components/parameters/Narrow'
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
queue_id:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The ID of the queue that has been allocated for your client.
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
last_event_id:
type: integer
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The initial value of `last_event_id` to pass to `GET /api/v1/events`.
api: Always return zulip_version/zulip_feature_level. We no longer make these conditional to simplify writing clients; there's no cost to including them, and a real cost to not doing so.
2020-04-29 12:39:39 +02:00
zulip_feature_level:
type: integer
description: |
The server's current [Zulip feature level](/api/changelog).
zulip_version:
type: string
description: |
The server's version.
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
- example:
{
"last_event_id": -1,
"msg": "",
"queue_id": "1517975029:0",
"realm_emoji": {
"1": {
api: Simplify format of realm_emoji author data. There's no reason to send data beyond the user `id` of the uploader, and reason not to, as the previous model was both awkward when `author=None` and resulted in unecessary parsing complexity for clients. Modified by tabbott to add the frontend changes and API documentation. Fixes #15115.
2020-05-29 11:11:48 +02:00
"author_id": 5,
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
"deactivated": false,
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/1/emoji/images/1.png"
}
},
api: Always return zulip_version/zulip_feature_level. We no longer make these conditional to simplify writing clients; there's no cost to including them, and a real cost to not doing so.
2020-04-29 12:39:39 +02:00
"result": "success",
"zulip_feature_level": 2,
"zulip_version": "2.1.0"
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
}
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
/server_settings:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_server_settings
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Fetch global settings for a Zulip server.
`GET {{ api_url }}/v1/server_settings`
**Note:** this endpoint does not require any authentication at all, and you can use it to check:
* If this is a Zulip server, and if so, what version of Zulip it's running.
* What a Zulip client (e.g. a mobile app or
[zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to
know in order to display a login prompt for the server (e.g. what
authentication methods are available).
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
authentication_methods:
type: object
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Each key-value pair in the object indicates whether the authentication
method is enabled on this server.
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
**Changes**: Deprecated in Zulip 2.1, in favor of the more expressive
`external_authentication_methods`.
properties:
password:
description: |
Whether the user can authenticate using password.
type: boolean
dev:
description: |
Whether the user can authenticate using development api key.
type: boolean
email:
description: |
Whether the user can authenticate using email.
type: boolean
ldap:
description: |
Whether the user can authenticate using ldap.
type: boolean
remoteuser:
description: |
Whether the user can authenticate using remoteuser.
type: boolean
github:
description: |
Whether the user can authenticate using their github account.
type: boolean
azuread:
description: |
Whether the user can authenticate using their azuread account.
type: boolean
gitlab:
description: |
Whether the user can authenticate using their gitlab account.
type: boolean
google:
description: |
Whether the user can authenticate using their google account.
type: boolean
saml:
description: |
Whether the user can authenticate using saml.
type: boolean
context: Rename social_backends to external_authentication_methods. The main purpose of this is to make that name change happen in /server_settings. external_authentication_methods is a much better, more descriptive name than social_backends from API perspective.
2019-11-03 23:51:49 +01:00
external_authentication_methods:
auth: Add social_backends to /server_settings.
2019-10-22 01:33:44 +02:00
type: array
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
A list of dictionaries describing the available external
authentication methods (E.g. Google, GitHub, or SAML)
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
enabled for this organization.
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
The list is sorted in the order in which these
authentication methods should be displayed.
api docs: Add an API changelog page. I imagine this can be improved in various ways, but I've initialized this with all the **Changes** entries recorded in either zulip.yaml or the rest of the API documentation, and I expect we'll be able to iterate on this effectively. It'll also be useful as a record of changes that we should remember to document the API documentation as we document more endpoints that currently don't discuss these issues. While working on this, I fixed various issues where feature levels could be mentioned or endpoints didn't properly document changes.
2020-04-29 05:55:42 +02:00
**Changes**: New in Zulip 2.1.
openapi: Pass validation of zulip.yaml on openapi-generator. The openapi-generator has an additional set of requirements for validation. Make changes in zulip.yaml accordingly.
2020-04-18 12:46:15 +02:00
items:
type: object
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
properties:
name:
type: string
description: |
A unique, table, machine-readable name for the authentication method,
intended to be used by clients with special behavior for specific
authenatication methods to correctly identify the method.
display_name:
type: string
description: |
Display name of the authentication method, to be used in all buttons
for the authentication method.
display_icon:
type: string
nullable: true
description: |
URL for an image to be displayed as an icon in all buttons for
the external authentication method.
When null, no icon should be displayed.
login_url:
type: string
description: |
URL to be used to initiate authentication using this method.
signup_url:
type: string
description: |
URL to be used to initiate account registration using this method.
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
zulip_version:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The version of Zulip running in the server.
api: Add a monotonic integer "feature level" for non-webapp clients. The purpose is to provide a way for (non-webapp) clients, like the mobile and terminal apps, to tell whether the server it's talking to is new enough to support a given API feature -- in particular a way that * is finer-grained than release numbers, so that for features developed after e.g. 2.1.0 we can use them immediately on servers deployed from master (like chat.zulip.org and zulipchat.com) without waiting the months until a 2.2 release; * is reliable, unlike e.g. looking at the number of commits since a release; * doesn't lead to a growing bag of named feature flags which the server has to go on sending forever. Tweaked by tabbott to extend the documentation. Closes #14618.
2020-04-20 00:57:28 +02:00
zulip_feature_level:
type: integer
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
An integer indicating what features are
available on the server. The feature level increases monotonically;
a value of N means the server supports all API features introduced
before feature level N. This is designed to provide a simple way
for client apps to decide whether the server supports a given
feature or API change. See the [changelog](/api/changelog) for
details on what each feature level means.
**Changes**. New in Zulip 2.2. We recommend using an implied value
of 0 for Zulip servers that do not send this field.
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
push_notifications_enabled:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether mobile/push notifications are enabled.
compatibility: Add a compatibility check to api_get_server_settings. This should make it convenient for the mobile app to present errors of the form "Your Zulip app is not new enough for this Zulip server".
2018-12-06 02:49:34 +01:00
is_incompatible:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether the Zulip client that has sent a request to this endpoint is
deemed incompatible with the server.
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
email_auth_enabled:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Setting for allowing users authenticate with an email-password
combination.
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
require_email_format_usernames:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
Whether all valid usernames for authentication to this
organization will be email addresses. This is important
for clients to know whether to do client side validation
of email address format in a login prompt.
This value will be false if the server has [LDAP
authentication][ldap-auth] enabled with a username and
password combination.
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
realm_uri:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
The organization's canonical URL.
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
realm_name:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
The organization's name (for display purposes).
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
realm_icon:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
The URL for the organization's logo formatted as a square image,
used for identifying the organization in small locations in the
mobile and desktop apps.
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
realm_description:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
HTML description of the organization, as configured by the [organization
profile](/help/create-your-organization-profile).
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
- example:
{
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
"authentication_methods": {
"password": true,
"dev": true,
"email": true,
"ldap": false,
"remoteuser": false,
"github": true,
"azuread": false,
"google": true,
"saml": true
},
"zulip_version": "2.0.6+git",
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
"push_notifications_enabled": false,
"msg": "",
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
"is_incompatible": false,
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
"email_auth_enabled": true,
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
"require_email_format_usernames": true,
"realm_uri": "http://localhost:9991",
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
"realm_name": "Zulip Dev",
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
"realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon",
"realm_description": "<p>The Zulip development environment default organization. It's great for testing!</p>",
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
"result": "success",
context: Rename social_backends to external_authentication_methods. The main purpose of this is to make that name change happen in /server_settings. external_authentication_methods is a much better, more descriptive name than social_backends from API perspective.
2019-11-03 23:51:49 +01:00
"external_authentication_methods": [
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
{
"name": "saml:idp_name",
"display_name": "SAML",
social_backends: If no icon is to be displayed, set display_icon to None.
2019-11-05 00:08:27 +01:00
"display_icon": null,
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
"login_url": "/accounts/login/social/saml/idp_name",
social_backends: Remove sort_order from social backend dicts. These are returned through the API, at the /server_settings endpoint. It's better to just return the list of dicts with a guarantee of being sorted in the correct order, than to clutter things with the sort_order field.
2019-11-02 04:35:39 +01:00
"signup_url": "/accounts/register/social/saml/idp_name"
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
},
{
"name": "google",
"display_name": "Google",
social_backends: Rename display_logo to display_icon.
2019-11-04 00:08:29 +01:00
"display_icon": "/static/images/landing-page/logos/googl_e-icon.png",
urls: Reorder where the accounts/login/google/ endpoint is defined. Needed so that the google entry in social_backends in /server_settings shows the new url rather than the legacy accounts/login/google/ url as the login url.
2019-11-02 00:05:57 +01:00
"login_url": "/accounts/login/social/google",
social_backends: Remove sort_order from social backend dicts. These are returned through the API, at the /server_settings endpoint. It's better to just return the list of dicts with a guarantee of being sorted in the correct order, than to clutter things with the sort_order field.
2019-11-02 04:35:39 +01:00
"signup_url": "/accounts/register/social/google"
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
},
{
"name": "github",
"display_name": "GitHub",
social_backends: Rename display_logo to display_icon.
2019-11-04 00:08:29 +01:00
"display_icon": "/static/images/landing-page/logos/github-icon.png",
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
"login_url": "/accounts/login/social/github",
social_backends: Remove sort_order from social backend dicts. These are returned through the API, at the /server_settings endpoint. It's better to just return the list of dicts with a guarantee of being sorted in the correct order, than to clutter things with the sort_order field.
2019-11-02 04:35:39 +01:00
"signup_url": "/accounts/register/social/github"
docs: Document social_backends in /server_settings. This updates the docs for the /server_settings endpoint to document the newly added social_backends structure.
2019-10-29 21:29:12 +01:00
}
]
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
}
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
/settings/notifications:
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_notification_settings
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
This endpoint is used to edit the user's global notification settings.
See [this endpoint](/api/update-subscription-properties) for
per-stream notification settings.
`PATCH {{ api_url }}/v1/settings/notifications`
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
parameters:
- name: enable_stream_desktop_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable visual desktop notifications for stream messages.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
- name: enable_stream_email_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable email notifications for stream messages.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
- name: enable_stream_push_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable mobile notifications for stream messages.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
- name: enable_stream_audible_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable audible desktop notifications for stream messages.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
- name: notification_sound
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Notification sound name.
openapi: Rectify wrong examples and schemas. Some examples mentioned in zulip.yaml did not match their schema. Change either the schema or the example so that all examples are valid with respect to their schemas.
2020-05-11 14:14:12 +02:00
content:
application/json:
schema:
type: string
example: ding
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
- name: enable_desktop_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable visual desktop notifications for private messages and @-mentions.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
- name: enable_sounds
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable audible desktop notifications for private messages and
@-mentions.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
- name: enable_offline_email_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable email notifications for private messages and @-mentions received
when the user is offline.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
- name: enable_offline_push_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable mobile notification for private messages and @-mentions received
when the user is offline.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
- name: enable_online_push_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable mobile notification for private messages and @-mentions received
when the user is online.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
- name: enable_digest_emails
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable digest emails when the user is away.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
example: true
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
- name: enable_login_emails
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Enable email notifications for new logins to account.
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
schema:
type: boolean
example: true
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
- name: message_content_in_email_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Include the message's content in missed messages email notifications.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
schema:
type: boolean
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
example: true
- name: pm_content_in_desktop_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Include content of private messages in desktop notifications.
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
schema:
type: boolean
example: true
settings: Add notification settings checkboxes for wildcard mentions. This change makes it possible for users to control the notification settings for wildcard mentions as a separate control from PMs and direct @-mentions.
2019-09-03 23:27:45 +02:00
- name: wildcard_mentions_notify
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
settings: Add notification settings checkboxes for wildcard mentions. This change makes it possible for users to control the notification settings for wildcard mentions as a separate control from PMs and direct @-mentions.
2019-09-03 23:27:45 +02:00
schema:
type: boolean
example: true
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
- name: desktop_icon_count_display
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
> Unread count summary (appears in desktop sidebar and browser tab)
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
* 1 - All unreads
* 2 - Private messages and mentions
* 3 - None
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: realm_name_in_notifications
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Include organization name in subject of missed message emails.
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
schema:
type: boolean
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
example: true
settings: Offer hiding presence info from other users. For privacy-minded folks who don't want to leak the information of whether they're online, this adds an option to disable sending presence updates to other users. The new settings lies in the "Other notification settings" section of the "Notification settings" page, under a "Presence" subheading. Closes #14798.
2020-05-01 20:39:26 +02:00
- name: presence_enabled
in: query
description: |
Display the presence status to other users when online.
schema:
type: boolean
example: true
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
enable_desktop_notifications:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `enable_desktop_notifications`, if it was changed in
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
this request.
enable_digest_emails:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `enable_digest_emails`, if it was changed in this
request.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
enable_offline_email_notifications:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `enable_offline_email_notifications`, if it was changed
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
in this request.
enable_offline_push_notifications:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `enable_offline_push_notifications`, if it was changed
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
in this request.
enable_online_push_notifications:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `enable_online_push_notifications`, if it was changed in
this request.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
enable_sounds:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `enable_sounds`, if it was changed in this request.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
enable_stream_email_notifications:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `enable_stream_email_notifications`, if it was changed
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
in this request.
enable_stream_push_notifications:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `enable_stream_push_notifications`, if it was changed in
this request.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
enable_stream_audible_notifications:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `enable_stream_audible_notifications`, if it was changed
in this request.
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
message_content_in_email_notifications:
type: boolean
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The setting for `message_content_in_email_notifications`, if it was
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
changed in this request.
- example:
{
"enable_offline_push_notifications": true,
"enable_online_push_notifications": true,
"msg": "",
"result": "success"
}
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
/streams:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_streams
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Get all streams that the user has access to.
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
`GET {{ api_url }}/v1/streams`
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
parameters:
- name: include_public
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Include all public streams.
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: true
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
example: false
- name: include_subscribed
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Include all streams that the user is subscribed to.
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: true
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
example: false
- name: include_all_active
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Include all active streams. The user must have administrative privileges
to use this parameter.
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
example: true
- name: include_default
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Include all default streams for the user's realm.
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
example: true
api/streams: Support including bot owner's subscriptions. This is important for situations such as with our Zapier app, where the requesting user may be a bot that would like to access its owner's subscriptions. Tweaked by tabbott to eliminate the 2^N growth of cases in do_get_streams.
2019-02-28 22:20:24 +01:00
- name: include_owner_subscribed
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
If the user is a bot, include all streams that the bot's owner is
subscribed to.
api/streams: Support including bot owner's subscriptions. This is important for situations such as with our Zapier app, where the requesting user may be a bot that would like to access its owner's subscriptions. Tweaked by tabbott to eliminate the 2^N growth of cases in do_get_streams.
2019-02-28 22:20:24 +01:00
schema:
type: boolean
default: false
example: true
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
streams:
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
description: |
A list of `stream` objects with details on the requested streams.
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
type: array
items:
type: object
openapi_responses: Fix get_streams.
2020-05-25 16:34:18 +02:00
properties:
stream_id:
type: integer
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
The unique ID of the stream.
openapi_responses: Fix get_streams.
2020-05-25 16:34:18 +02:00
name:
type: string
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
The name of the stream.
openapi_responses: Fix get_streams.
2020-05-25 16:34:18 +02:00
description:
type: string
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
The short description of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
invite_only:
type: boolean
openapi_responses: Fix get_streams.
2020-05-25 16:34:18 +02:00
description: |
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
Specifies whether the stream is private or not.
openapi_responses: Fix get_streams.
2020-05-25 16:34:18 +02:00
Only people who have been invited can access a private stream.
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
rendered_description:
type: string
description: |
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
is_web_public:
type: boolean
description: |
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
stream_post_policy:
type: integer
description: |
Policy for which users can post messages to the stream.
* 1 => Any user can post.
* 2 => Only administrators can post.
* 3 => Only new members can post.
**Changes**: New in Zulip 2.2, replacing the previous
`is_announcement_only` boolean.
history_public_to_subscribers:
type: boolean
description: |
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
first_message_id:
type: integer
description: |
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
is_announcement_only:
type: boolean
description: |
Whether the given stream is announcement only or not.
**Changes**: Deprecated in Zulip 2.2 (feature level 1), use
`stream_post_policy` instead.
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
- example:
{
"msg": "",
"result": "success",
"streams": [
{
"description": "A Scandinavian country",
"invite_only": false,
"name": "Denmark",
"stream_id": 1
},
{
"description": "Yet another Italian city",
"invite_only": false,
"name": "Rome",
"stream_id": 2
},
{
"description": "Located in the United Kingdom",
"invite_only": false,
"name": "Scotland",
"stream_id": 3
},
{
"description": "A northeastern Italian city",
"invite_only": false,
"name": "Venice",
"stream_id": 4
},
{
"description": "A city in Italy",
"invite_only": false,
"name": "Verona",
"stream_id": 5
},
{
"description": "New stream for testing",
"invite_only": false,
"name": "new stream",
"stream_id": 6
}
]
}
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
"result": "error"
}
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
/streams/{stream_id}:
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: delete_stream
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
[Delete the stream](/help/delete-a-stream) with the ID `stream_id`.
`DELETE {{ api_url }}/v1/streams/{stream_id}`
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
parameters:
api_docs: Add "StreamIdInPath" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in path) in components.
2020-04-19 10:30:30 +02:00
- $ref: '#/components/parameters/StreamIdInPath'
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- example:
{
"msg": "",
"result": "success"
}
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
- properties:
msg:
type: string
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
"result": "error"
}
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_stream
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Configure the stream with the ID `stream_id`. This endpoint supports
an organization administrator editing any property of a stream,
including:
* Stream [name](/help/rename-a-stream) and [description](/help/change-the-stream-description)
* Stream [permissions](/help/stream-permissions), including
[privacy](/help/change-the-privacy-of-a-stream) and [who can
send](/help/stream-sending-policy).
`PATCH {{ api_url }}/v1/streams/{stream_id}`
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
parameters:
api_docs: Add "StreamIdInPath" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in path) in components.
2020-04-19 10:30:30 +02:00
- $ref: '#/components/parameters/StreamIdInPath'
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
- name: description
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The new description for the stream.
openapi: Rectify wrong examples and schemas. Some examples mentioned in zulip.yaml did not match their schema. Change either the schema or the example so that all examples are valid with respect to their schemas.
2020-05-11 14:14:12 +02:00
content:
application/json:
schema:
type: string
example: This stream is related to football dicsussions.
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
required: false
- name: new_name
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The new name for the stream.
openapi: Rectify wrong examples and schemas. Some examples mentioned in zulip.yaml did not match their schema. Change either the schema or the example so that all examples are valid with respect to their schemas.
2020-05-11 14:14:12 +02:00
content:
application/json:
schema:
type: string
example: Italy
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
required: false
- name: is_private
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Change whether the stream is a private stream.
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
schema:
type: boolean
example: true
required: false
- name: is_announcement_only
in: query
docs: Document changes in the API made since Zulip 2.1.x. This is important documentation for anyone working on writing clients for the Zulip APIs that wants to support older releases.
2020-03-27 01:45:03 +01:00
description: |
Whether the stream is limited to announcements.
api docs: Add an API changelog page. I imagine this can be improved in various ways, but I've initialized this with all the **Changes** entries recorded in either zulip.yaml or the rest of the API documentation, and I expect we'll be able to iterate on this effectively. It'll also be useful as a record of changes that we should remember to document the API documentation as we document more endpoints that currently don't discuss these issues. While working on this, I fixed various issues where feature levels could be mentioned or endpoints didn't properly document changes.
2020-04-29 05:55:42 +02:00
**Changes**: Deprecated in Zulip 2.2 (feature level 1), use
`stream_post_policy` instead.
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
schema:
type: boolean
example: true
required: false
api_docs: Add "StreamPostPolicy" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_post_policy" in components.
2020-04-21 21:53:33 +02:00
- $ref: '#/components/parameters/StreamPostPolicy'
api_docs: Add HistoryPublicToSubscribers component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "history_public_to_subscribers" in components.
2020-04-21 21:56:47 +02:00
- $ref: '#/components/parameters/HistoryPublicToSubscribers'
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
api_docs: Add documentation for delete_stream.
2019-06-22 08:22:32 +02:00
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- example:
{
"msg": "",
"result": "success"
}
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
'400':
description: Bad request.
content:
application/json:
schema:
api_docs: Add documentation for delete_stream.
2019-06-22 08:22:32 +02:00
allOf:
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
- $ref: '#/components/schemas/JsonError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
"result": "error"
}
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
/typing:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: set_typing_status
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Send an event indicating that the user has started or stopped typing
on their client. See
[the typing notification docs](https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html)
for details on Zulip's typing notifications protocol.
`POST {{ api_url }}/v1/typing`
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
parameters:
- name: op
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Whether the user has started (`start`) or stopped (`stop`) to type.
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
schema:
type: string
enum:
- start
- stop
example: start
required: true
api docs: Fix typo in typing notifications docs. notification_to should be just to here. This resulted from the person doing the port into these docs not understanding the full REQ API.
2019-04-23 20:24:07 +02:00
- name: to
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
in: query
api docs: Document historical changes to typing API. Along with other recent changes, this fixes #13286.
2020-03-07 02:49:01 +01:00
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
The user_ids of the recipients of the message being typed. Typing
notifications are only supported for private messages. Send a
JSON-encoded list of user_ids. (Use a list even if there is only one
recipient.).
api docs: Document historical changes to typing API. Along with other recent changes, this fixes #13286.
2020-03-07 02:49:01 +01:00
**Changes**: Before Zulip 2.0, this parameter accepted only a JSON-encoded
list of email addresses. The email address-based format is deprecated
and will be removed in Zulip 2.2.
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
schema:
type: array
items:
typing: Deprecate emails in typing endpoint. The only clients that should use the typing indicators endpoint are our internal clients, and they should send a JSON-formatted list of user_ids. Unfortunately, we still have some older versions of mobile that still send emails. In this commit we fix non-user-facing things like docs and tests to promote the user_ids interface that has existed since about version 2.0 of the server. One annoyance is that we documented the typing endpoint with emails, instead of the more modern user_ids, which may have delayed mobile converting to user_ids (and which certainly caused confusion). It's trivial to update the docs, but we need to short circuit one assertion in the openapi tests. We also clean up the test structure for the typing tests: TypingHappyPathTest.test_start_to_another_user TypingHappyPathTest.test_start_to_multiple_recipients TypingHappyPathTest.test_start_to_self TypingHappyPathTest.test_start_to_single_recipient TypingHappyPathTest.test_stop_to_another_user TypingHappyPathTest.test_stop_to_self TypingValidateOperatorTest.test_invalid_parameter TypingValidateOperatorTest.test_missing_parameter TypingValidateUsersTest.test_argument_to_is_not_valid_json TypingValidateUsersTest.test_bogus_user_id TypingValidateUsersTest.test_empty_array TypingValidateUsersTest.test_missing_recipient TypingValidationHelpersTest.test_recipient_for_user_ids TypingValidationHelpersTest.test_recipient_for_user_ids_non_existent_id TypingLegacyMobileSupportTest.test_legacy_email_interface
2020-02-22 13:38:09 +01:00
type: integer
example: [9, 10]
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
/user_groups/create:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: create_user_group
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Create a new [user group](/help/user-groups).
`POST {{ api_url }}/v1/user_groups/create`
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
parameters:
- name: name
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The name of the user group.
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
schema:
type: string
example: marketing
required: true
- name: description
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The description of the user group.
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
schema:
type: string
example: The marketing team.
required: true
- name: members
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
An array containing the user IDs of the initial members for the
new user group.
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
schema:
type: array
openapi: Fix some errors caught by online editor. This fixes several values that had invalid types recorded.
2019-07-31 01:36:50 +02:00
items:
type: integer
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
example: [1, 2, 3, 4]
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- example:
{
"msg": "",
"result": "success"
}
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
"result": "error",
"code": "BAD_REQUEST",
"msg": "Invalid user ID: 500"
}
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
/user_groups/{group_id}:
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_user_group
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Update the name or description of a [user group](/help/user-groups).
`PATCH {{ api_url }}/v1/user_groups/{group_id}`
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
parameters:
api_docs: Add "GroupId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "group_id" in components.
2020-04-18 10:54:51 +02:00
- $ref: '#/components/parameters/GroupId'
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
- name: name
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The new name of the group.
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
schema:
type: string
tests: Remove update-user-group from curl test exclude_list.
2019-11-14 09:35:28 +01:00
example: marketing team
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
required: true
- name: description
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The new description of the group.
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
schema:
type: string
example: The marketing team.
required: true
responses:
'200':
openapi: Use response schema for describing simple success response. In zulip.yaml simple json success response which only contains 'msg' and 'result' properties has been described repeatedly in multiple endpoints. Instead, use SimpleSuccess template for such responses to increase code modularity and reusablility.
2020-03-29 15:55:14 +02:00
$ref: '#/components/responses/SimpleSuccess'
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid user group",
"result": "error"
}
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: remove_user_group
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Delete a [user group](/help/user-groups).
`DELETE {{ api_url }}/v1/user_groups/{group_id}`
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
parameters:
api_docs: Add "GroupId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "group_id" in components.
2020-04-18 10:54:51 +02:00
- $ref: '#/components/parameters/GroupId'
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- example:
{
"result": "success",
"msg": "",
}
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid user group",
"result": "error"
}
api: Add GET /user_groups documentation. This documents our GET endpoint for interacting with Zulip's user groups feature. Fixes #10298.
2018-08-18 23:06:53 +02:00
/user_groups:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_user_groups
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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
Fetches all of the user groups in the organization.
`GET {{ api_url }}/v1/user_groups`
api: Add GET /user_groups documentation. This documents our GET endpoint for interacting with Zulip's user groups feature. Fixes #10298.
2018-08-18 23:06:53 +02:00
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
user_groups:
type: array
items:
type: object
openapi_responses: Fix get_user_groups.
2020-05-27 14:11:41 +02:00
properties:
description:
type: string
description: |
The human-readable description of the user group.
id:
type: integer
description: |
The user group's integer id.
members:
type: array
description: |
The integer User IDs of the user group members.
items:
type: integer
name:
type: string
description: |
User group name.
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of `user_group` objects, which contain a `description`, a `name`,
their `id` and the list of members of the user group.
api: Add GET /user_groups documentation. This documents our GET endpoint for interacting with Zulip's user groups feature. Fixes #10298.
2018-08-18 23:06:53 +02:00
- example:
{
"msg": "",
"result": "success",
"user_groups": [
{
"description": "Characters of Hamlet",
"id": 1,
"name": "hamletcharacters",
"members": [3, 4]
},
{
"description": "Other users",
"id": 2,
"name": "other users",
"members": [1, 2]
}
]
}
api docs: Migrate REAL-TIME /events to OpenAPI. Migrate "call_on_each_event" from api/arguments.json to /events:real-time in OpenAPI. This is a bit of a hack, but it lets us eliminate this secondary arguments.json file, which is probably worth it. Tweaked by tabbott to fix various formatting issues in the original documentation while I was looking at it.
2020-03-18 02:40:44 +01:00
/real-time:
# This entry is a hack; it exists to give us a place to put the text
# documenting the arguments for call_on_each_event and friends.
post:
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
(Ignored)
api docs: Migrate REAL-TIME /events to OpenAPI. Migrate "call_on_each_event" from api/arguments.json to /events:real-time in OpenAPI. This is a bit of a hack, but it lets us eliminate this secondary arguments.json file, which is probably worth it. Tweaked by tabbott to fix various formatting issues in the original documentation while I was looking at it.
2020-03-18 02:40:44 +01:00
parameters:
api_docs: Add "Narrow" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "narrow" in components.
2020-04-18 10:13:13 +02:00
- $ref: '#/components/parameters/Narrow'
api_docs: Add "event_types" common component. To facilitate re-use of the same parameters in other paths. this commit store the content of the parameter "event_types" in components.
2020-04-15 08:24:00 +02:00
- $ref: '#/components/parameters/Event_types'
openapi: Rectify wrong examples and schemas. Some examples mentioned in zulip.yaml did not match their schema. Change either the schema or the example so that all examples are valid with respect to their schemas.
2020-05-11 14:14:12 +02:00
example: ['message']
api docs: Migrate REAL-TIME /events to OpenAPI. Migrate "call_on_each_event" from api/arguments.json to /events:real-time in OpenAPI. This is a bit of a hack, but it lets us eliminate this secondary arguments.json file, which is probably worth it. Tweaked by tabbott to fix various formatting issues in the original documentation while I was looking at it.
2020-03-18 02:40:44 +01:00
security:
- basicAuth: []
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
responses:
# Makeshift response for this hack entry.
'200':
description: Success
api_docs: Migrate POST /rest-error-handling. This commit migrates payload of errors which are common to many endpoints to /rest-error-handling:post in OpenAPI.
2020-04-02 02:15:28 +02:00
/rest-error-handling:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: rest_error_handling
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
api_docs: Migrate POST /rest-error-handling. This commit migrates payload of errors which are common to many endpoints to /rest-error-handling:post in OpenAPI.
2020-04-02 02:15:28 +02:00
description: |
Common error to many endpoints
responses:
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
'400':
api_docs: Migrate POST /rest-error-handling. This commit migrates payload of errors which are common to many endpoints to /rest-error-handling:post in OpenAPI.
2020-04-02 02:15:28 +02:00
description: |
Bad request.
content:
application/json:
schema:
openapi: Make zulip.yaml pass validation on swagger editor. zulip.yaml is not in compliance with openapi specifications file. Edit it so that it passes verification as an openapi specification file. Fixes #14582 .
2020-04-17 16:16:43 +02:00
oneOf:
- allOf:
- $ref: '#/components/schemas/InvalidApiKeyError'
- allOf:
- $ref: '#/components/schemas/MissingArgumentError'
- allOf:
- $ref: '#/components/schemas/UserNotAuthorizedError'
api_docs: Migrate POST /zulip-outgoing-webhook. This commit migrates zulip outging webhook payload to /zulip-outgoing-webhook:post in OpenAPI. Since this migrates the last payloads from api/fixtures.json to OpenAPI, this commit removes api/fixtures.json file and the functions accessing the file. Tweaked by tabbott to further remove an unnecessary conditional.
2020-04-02 03:42:59 +02:00
/zulip-outgoing-webhook:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: zulip_outgoing_webhooks
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["webhooks"]
api_docs: Migrate POST /zulip-outgoing-webhook. This commit migrates zulip outging webhook payload to /zulip-outgoing-webhook:post in OpenAPI. Since this migrates the last payloads from api/fixtures.json to OpenAPI, this commit removes api/fixtures.json file and the functions accessing the file. Tweaked by tabbott to further remove an unnecessary conditional.
2020-04-02 03:42:59 +02:00
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
Outgoing Webhooks allows to build or set up Zulip integrations which are
notified when certain types of messages are sent in Zulip.
api_docs: Migrate POST /zulip-outgoing-webhook. This commit migrates zulip outging webhook payload to /zulip-outgoing-webhook:post in OpenAPI. Since this migrates the last payloads from api/fixtures.json to OpenAPI, this commit removes api/fixtures.json file and the functions accessing the file. Tweaked by tabbott to further remove an unnecessary conditional.
2020-04-02 03:42:59 +02:00
responses:
'200':
description: |
Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
data:
type: string
description: |
It contains the content of the message (in Markdown).
trigger:
type: string
description: |
It contains the trigger method.
token:
type: string
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
A string of alphanumeric characters that can be use to authenticate the
webhook request (each bot user uses a fixed token).
api_docs: Migrate POST /zulip-outgoing-webhook. This commit migrates zulip outging webhook payload to /zulip-outgoing-webhook:post in OpenAPI. Since this migrates the last payloads from api/fixtures.json to OpenAPI, this commit removes api/fixtures.json file and the functions accessing the file. Tweaked by tabbott to further remove an unnecessary conditional.
2020-04-02 03:42:59 +02:00
message:
type: object
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
A dict containing details on the message which triggered the outgoing
webhook
api_docs: Migrate POST /zulip-outgoing-webhook. This commit migrates zulip outging webhook payload to /zulip-outgoing-webhook:post in OpenAPI. Since this migrates the last payloads from api/fixtures.json to OpenAPI, this commit removes api/fixtures.json file and the functions accessing the file. Tweaked by tabbott to further remove an unnecessary conditional.
2020-04-02 03:42:59 +02:00
bot_email:
type: string
description: |
Email of the bot user
- example:
{
"data": "@**Outgoing Webhook Test** Zulip is the world\u2019s most productive group chat!",
"trigger": "mention",
"token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0",
"message": {
"subject": "Verona2",
"sender_email": "iago@zulip.com",
"timestamp": 1527876931,
"client": "website",
"submessages": [
],
"recipient_id": 20,
"topic_links": [
],
"sender_full_name": "Iago",
"avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1",
"rendered_content": "<p><span class=\"user-mention\" data-user-id=\"25\">@Outgoing Webhook Test</span> Zulip is the world\u2019s most productive group chat!</p>",
"sender_id": 5,
"stream_id": 5,
"content": "@**Outgoing Webhook Test** Zulip is the world\u2019s most productive group chat!",
"display_recipient": "Verona",
"type": "stream",
"id": 112,
"is_me_message": false,
"reactions": [
],
"sender_realm_str": "zulip",
"sender_short_name": "iago"
},
"bot_email": "outgoing-bot@localhost"
}
api docs: Migrate REAL-TIME /events to OpenAPI. Migrate "call_on_each_event" from api/arguments.json to /events:real-time in OpenAPI. This is a bit of a hack, but it lets us eliminate this secondary arguments.json file, which is probably worth it. Tweaked by tabbott to fix various formatting issues in the original documentation while I was looking at it.
2020-03-18 02:40:44 +01:00
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
components:
#######################
# Security definitions
#######################
securitySchemes:
BasicAuth:
type: http
scheme: basic
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Basic authentication, with the user's email as the username, and the API
key as the password. The API key can be fetched using the
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
schemas:
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
User:
type: object
description: |
A dictionary containing basic data on a given Zulip user.
properties:
email:
type: string
description: |
The Zulip API email address of the user or bot.
If you do not have permission to view the email address of the target user,
this will be a fake email address that is usable for the Zulip API but nothing else.
is_bot:
type: boolean
description: |
A boolean specifying whether the user is a bot or full account.
avatar_url:
type: string
nullable: true
description: |
URL for the the user's avatar. Will be `null` if the `client_gravatar`
query parameter was set to `True` and the user's avatar is hosted by
the Gravatar provider (i.e. the user has never uploaded an avatar).
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
avatar_version:
type: integer
description: |
Version for the the user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
full_name:
type: string
description: |
Full name of the user or bot, used for all display purposes.
is_admin:
type: boolean
description: |
A boolean specifying whether the user is an organization administrator.
users: Add is_owner field to user objects returned by get endpoints. This commit adds 'is_owner' field to the user object returned by '/users', 'users/{user_id}', and '/users/me' endpoints.
2020-06-01 21:47:18 +02:00
is_owner:
type: boolean
description: |
A boolean specifying whether the user is an organization owner.
If true, is_admin will also be true.
**Changes**: New in Zulip 2.2 (feature level 8).
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
bot_type:
type: integer
nullable: true
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
An integer describing the type of bot:
* `null` if the user isn't a bot.
* `1` for a `Generic` bot.
* `2` for an `Incoming webhook` bot.
* `3` for an `Outgoing webhook` bot.
* `4` for an `Embedded` bot.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
user_id:
type: integer
description: |
The unique ID of the user.
bot_owner_id:
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
type: integer
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
nullable: true
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
If the user is a bot (i.e. `is_bot` is `True`),
`bot_owner` is the user ID of the bot's owner (usually, whoever
created the bot).
Will be null for legacy bots that do not have an owner.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
**Changes**: New in Zulip 2.2 (feature level
1). In previous versions, there was a `bot_owner` field
containing the email address of the bot's owner.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
is_active:
type: boolean
description: |
A boolean specifying whether the user account has been deactivated.
is_guest:
type: boolean
description: |
A boolean specifying whether the user is a guest user.
timezone:
type: string
description: |
The time zone of the user.
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
date_joined:
type: string
description: |
The time the user account was created.
profile_data:
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
$ref: '#/components/schemas/profile_data'
profile_data:
type: object
description: |
A dictionary containing custom profile field data for the user. Each entry
maps the integer ID of a custom profile field in the organization to a
dictionary containing the user's data for that field. Generally the data
includes just a single `value` key; for those custom profile fields
supporting markdown, a `rendered_value` key will also be present.
additionalProperties:
type: object
description: |
'{id}': Object with data about what value user filled in the custom
profile field with id `id`.
properties:
value:
type: string
description: |
User's personal value for this custom profile field.
rendered_value:
type: string
description: |
The `value` rendered in HTML. Will only be present for
custom profile field types that support markdown rendering.
This user-generated HTML content should be rendered
using the same CSS and client-side security protections
as are used for message content.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
JsonResponse:
type: object
properties:
docs: Amend definitions of JSON responses.
2017-06-25 17:52:59 +02:00
result:
docs: Fix JsonSuccess and JsonError models.
2017-05-24 05:22:50 +02:00
type: string
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
JsonSuccess:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- success
msg:
type: string
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
- example:
{
"msg": "",
"result": "success"
}
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
JsonError:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- error
msg:
type: string
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
ApiKeyResponse:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
- required:
- api_key
- email
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
- properties:
api_key:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The API key that can be used to authenticate as the requested user.
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
email:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The email address of the user who owns the API key.
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
- example:
{
"api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv",
"email": "iago@zulip.com",
"msg": "",
"result": "success"
}
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
CodedError:
allOf:
- $ref: '#/components/schemas/JsonError'
- properties:
code:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A string that identifies the error.
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
BadEventQueueIdError:
allOf:
- $ref: '#/components/schemas/CodedError'
- properties:
queue_id:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The string that identifies the invalid event queue.
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
- example:
{
"code": "BAD_EVENT_QUEUE_ID",
"msg": "Bad event queue id: 1518820930:1",
"queue_id": "1518820930:1",
"result": "error"
}
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
InvalidMessageError:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
raw_content:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The raw content of the message.
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
- example:
{
"msg": "Invalid message(s)",
"code": "BAD_REQUEST",
"result": "error"
}
api docs: Create the NonExistingStreamError schema definition.
2018-06-21 02:25:29 +02:00
NonExistingStreamError:
allOf:
- $ref: '#/components/schemas/CodedError'
- properties:
stream:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
The name of the stream that could not be found.
api docs: Create the NonExistingStreamError schema definition.
2018-06-21 02:25:29 +02:00
- example:
{
"code": "STREAM_DOES_NOT_EXIST",
"msg": "Stream 'nonexistent_stream' does not exist",
"result": "error",
"stream": "nonexistent_stream"
}
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
AddSubscriptionsResponse:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
subscribed:
type: object
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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.
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
additionalProperties:
description: |
`{email_address}`: List of the names of the streams that were subscribed
to as a result of the query.
type: array
items:
type: string
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
already_subscribed:
type: object
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
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.
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
additionalProperties:
description: |
{email_address}`: List of the names of the streams that the user is
already subscribed to.
type: array
items:
type: string
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
unauthorized:
type: array
items:
type: string
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of names of streams that the requesting user/bot was not
authorized to subscribe to.
api_docs: Move /rest-error-handling examples. This commit moves /rest-error-handling examples to components section so that they can be re-used in individual endpoints where it's example can be highlighted more easiy.
2020-04-15 09:23:24 +02:00
InvalidApiKeyError:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
"msg": "Invalid API key",
"result": "error"
}
MissingArgumentError:
allOf:
- $ref: '#/components/schemas/CodedError'
- properties:
var_name:
type: string
description: |
It contains the information about the missing argument.
- example:
{
"code": "REQUEST_VARIABLE_MISSING",
"msg": "Missing 'content' argument",
"result": "error",
"var_name": "content"
}
UserNotAuthorizedError:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
"result": "error"
}
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
###################
# Shared responses
###################
responses:
SimpleSuccess:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
docs: Document /messages API endpoint.
2017-05-24 01:54:20 +02:00
content:
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
api_docs: Add "event_types" common component. To facilitate re-use of the same parameters in other paths. this commit store the content of the parameter "event_types" in components.
2020-04-15 08:24:00 +02:00
####################
# Shared parameters
####################
parameters:
Event_types:
name: event_types
in: query
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
A JSON-encoded array indicating which types of events you're interested
in. Values that you might find useful include:
api_docs: Add "event_types" common component. To facilitate re-use of the same parameters in other paths. this commit store the content of the parameter "event_types" in components.
2020-04-15 08:24:00 +02:00
* **message** (messages)
* **subscription** (changes in your subscriptions)
* **realm_user** (changes to users in the organization and
their properties, such as their name).
If you do not specify this argument, you will receive all
events, and have to filter out the events not relevant to
your client in your client code. For most applications, one
is only interested in messages, so one specifies:
`event_types=['message']`
schema:
type: array
items:
type: string
required: false
api_docs: Add "Narrow" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "narrow" in components.
2020-04-18 10:13:13 +02:00
Narrow:
name: narrow
in: query
description: |
A JSON-encoded array of length 2 indicating the narrow for which you'd
like to receive events for. For instance, to receive events for the
stream `Denmark`, you would specify `narrow=['stream', 'Denmark']`.
Another example is `narrow=['is', 'private']` for private messages.
Default is `[]`.
schema:
type: array
items:
anyOf:
- type: string
- type: integer
default: []
example: ['stream', 'Denmark']
required: false
api_docs: Add "GroupId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "group_id" in components.
2020-04-18 10:54:51 +02:00
GroupId:
name: group_id
in: path
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The ID of the target user group.
api_docs: Add "GroupId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "group_id" in components.
2020-04-18 10:54:51 +02:00
schema:
type: integer
example: 42
required: true
api_docs: Add "Topic" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "topic" in components.
2020-04-18 11:14:08 +02:00
Topic:
name: topic
in: query
description: |
The topic of the message. Only required for stream messages
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
(`type="stream"`), ignored otherwise.
Maximum length of 60 characters.
api_docs: Add "Topic" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "topic" in components.
2020-04-18 11:14:08 +02:00
schema:
type: string
example: Castle
api_docs: Add "QueueId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "queue_id" in components.
2020-04-18 17:35:53 +02:00
QueueId:
name: queue_id
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The ID of an event queue that was previously registered via `POST
/api/v1/register` (see [Register a queue](/api/register-queue)).
api_docs: Add "QueueId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "queue_id" in components.
2020-04-18 17:35:53 +02:00
schema:
type: string
example: 1375801870:2942
required: true
api_docs: Add "Stream" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream" in components.
2020-04-18 17:59:13 +02:00
Stream:
name: stream
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The name of the stream to access.
api_docs: Add "Stream" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream" in components.
2020-04-18 17:59:13 +02:00
schema:
type: string
example: Denmark
api_docs: Add "StreamIdInQuery" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in query) in components.
2020-04-19 10:01:44 +02:00
StreamIdInQuery:
name: stream_id
in: query
description: |
The ID of the stream to access.
schema:
type: integer
example: 42
api_docs: Add "StreamIdInPath" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in path) in components.
2020-04-19 10:30:30 +02:00
StreamIdInPath:
name: stream_id
in: path
description: |
The ID of the stream to access.
schema:
type: integer
example: 42
required: true
api_docs: Add "ClientGravatar" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "client_gravatar" in components.
2020-04-19 11:21:51 +02:00
ClientGravatar:
name: client_gravatar
in: query
description: |
Whether the client supports computing gravatars URLs. If
enabled, `avatar_url` will be included in the response only
if there is a Zulip avatar, and will be `null` for users who
are using gravatar as their avatar. This option
significantly reduces the compressed size of user data,
since gravatar URLs are long, random strings and thus do not
compress well. The `client_gravatar` field is set to `true` if
clients can compute their own gravatars.
schema:
type: boolean
default: false
example: true
api_docs: Add "Content" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "content" in components.
2020-04-19 11:46:51 +02:00
Content:
name: content
in: query
description: |
The content of the message. Maximum message size of 10000 bytes.
schema:
type: string
example: Hello
required: true
api_docs: Add "MessageId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "message_id" in components.
2020-04-20 16:46:14 +02:00
MessageId:
name: message_id
in: path
description: |
The target message's ID.
schema:
type: integer
example: 42
required: true
api_docs: Add "UserId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "user_id" in components.
2020-04-21 21:44:21 +02:00
UserId:
name: user_id
in: path
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The target user's ID.
api_docs: Add "UserId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "user_id" in components.
2020-04-21 21:44:21 +02:00
schema:
type: integer
populate_db: Add new admin user as 'Desdemona'. This commit adds a second admin user named 'Desdemona' to dev and test database.
2020-05-17 18:46:14 +02:00
example: 12
api_docs: Add "UserId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "user_id" in components.
2020-04-21 21:44:21 +02:00
required: true
api_docs: Add "StreamPostPolicy" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_post_policy" in components.
2020-04-21 21:53:33 +02:00
StreamPostPolicy:
name: stream_post_policy
in: query
description: |
Policy for which users can post messages to the stream.
* 1 => Any user can post.
* 2 => Only administrators can post.
* 3 => Only new members can post.
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
**Changes**: New in Zulip 2.2, replacing the previous
`is_announcement_only` boolean.
api_docs: Add "StreamPostPolicy" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_post_policy" in components.
2020-04-21 21:53:33 +02:00
schema:
type: integer
default: 1
example: 2
required: false
api_docs: Add HistoryPublicToSubscribers component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "history_public_to_subscribers" in components.
2020-04-21 21:56:47 +02:00
HistoryPublicToSubscribers:
name: history_public_to_subscribers
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
Whether the stream's message history should be available to
newly subscribed members, or users can only access messages
they actually received while subscribed to the stream.
Corresponds to the [shared history](/help/stream-permissions)
option in documentation.
api_docs: Add HistoryPublicToSubscribers component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "history_public_to_subscribers" in components.
2020-04-21 21:56:47 +02:00
schema:
type: boolean
default: None
example: false
required: false
api_docs: Add "IncludeSubscribers" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "IncludeSubscribers" in components.
2020-04-21 22:14:11 +02:00
IncludeSubscribers:
name: include_subscribers
in: query
description: |
Whether each returned stream object should include a `subscribers`
field containing a list of the user IDs of its subscribers.
(This may be significantly slower in organizations with
thousands of users subscribed to many streams.)
**Changes**: New in Zulip 2.1.0.
schema:
type: boolean
default: false
example: true
api_docs: Add "EmojiName" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_name" in components.
2020-04-21 22:24:18 +02:00
EmojiName:
name: emoji_name
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The target emoji's human-readable name.
api_docs: Add "EmojiName" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_name" in components.
2020-04-21 22:24:18 +02:00
To find an emoji's name, hover over a message to reveal
three icons on the right, then click the smiley face icon.
Images of available reaction emojis appear. Hover over the
emoji you want, and note that emoji's text name.
schema:
type: string
example: 'octopus'
api_docs: Add IncludeCustomProfileFields component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "include_custom_profile_fields" in components.
2020-04-21 22:26:12 +02:00
IncludeCustomProfileFields:
name: include_custom_profile_fields
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
Whether the client wants [custom profile field](/help/add-custom-profile-fields)
data to be included in the response.
api_docs: Add IncludeCustomProfileFields component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "include_custom_profile_fields" in components.
2020-04-21 22:26:12 +02:00
**Changes**: New in Zulip 2.1.0. Previous versions do no offer these
data via the API.
schema:
type: boolean
default: false
example: true
api_docs: Add "Principals" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "principals" in components.
2020-04-21 22:27:56 +02:00
Principals:
name: principals
in: query
description: |
stream: Add support for sending user_id to endpoint when subscribing users. This commit modifies the backend to accept user ids when subscribing users to streams. It also migrates all existing tests to use this API, aside from a small set of tests for the legacy API.
2020-04-09 19:07:57 +02:00
A list of user ids (preferred) or Zulip display email
addresses of the users to be subscribed to or unsubscribed
from the streams specified in the `subscriptions` argument. If
not provided, then the requesting user/bot is subscribed.
**Changes**: The integer format is new in Zulip 2.2 (Feature level 9).
api_docs: Add "Principals" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "principals" in components.
2020-04-21 22:27:56 +02:00
schema:
type: array
items:
stream: Add support for sending user_id to endpoint when subscribing users. This commit modifies the backend to accept user ids when subscribing users to streams. It also migrates all existing tests to use this API, aside from a small set of tests for the legacy API.
2020-04-09 19:07:57 +02:00
oneOf:
- type: string
- type: integer
api_docs: Add "Principals" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "principals" in components.
2020-04-21 22:27:56 +02:00
default: []
example: ['ZOE@zulip.com']
api_docs: Add "ReactionType" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "reaction_type" in components.
2020-04-21 22:29:35 +02:00
ReactionType:
name: reaction_type
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
If an app is adding/removing a vote on an existing reaction,
it should pass this parameter using the value the server provided
for the existing reaction for specificity. Supported values:
* `unicode_emoji`: Unicode emoji (`emoji_code` will be its unicode codepoint).
* `realm_emoji`: Custom emoji. (`emoji_code` will be its ID).
* `zulip_extra_emoji`: Special emoji included with Zulip. Exists to
namespace the `zulip` emoji.
**Changes**: In Zulip 2.2 (feature level 2), this become
optional for [custom emoji](/help/add-custom-emoji);
previously, this endpoint assumed `unicode_emoji` if this
parameter was not specified.
api_docs: Add "ReactionType" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "reaction_type" in components.
2020-04-21 22:29:35 +02:00
schema:
type: string
example: 'unicode_emoji'
required: false
api_docs: Add "EmojiCode" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_code" in components.
2020-04-24 03:02:15 +02:00
EmojiCode:
name: emoji_code
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
A unique ID, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`.
For most API clients, you won't need this, but it's important
for Zulip apps to handle rare corner cases when
adding/removing votes on an emoji reaction added previously by
another user.
If the existing reaction was added when the Zulip server was
using a previous version of the emoji data mapping between
Unicode codepoints and human-readable names, sending the
`emoji_code` in the data for the original reaction allows the
Zulip server to correctly interpret your upvote as an upvote
api_docs: Add "EmojiCode" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_code" in components.
2020-04-24 03:02:15 +02:00
rather than a reaction with a "diffenent" emoji.
schema:
type: string
example: '1f419'
required: false