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

3853 lines
136 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:
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.
operationId: zerver.views.auth.api_fetch_api_key
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: 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: 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
set) of events with IDs newer than `last_event_id`. Event IDs are
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 "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: 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: 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: 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: 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: 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
- 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: 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.
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
schema:
type: string
docs: Recommend user_id instead of email in send-message doc. Also stop documenting the legacy method of sending emails in CSV format.
2020-03-06 08:44:00 +01:00
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: |
The ID assigned to the message sent.
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: 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: 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: 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: 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: 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
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
message after the edition.
- 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: 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: 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: 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'
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
- name: emoji_name
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
Name of the emoji you want to add as as a reaction.
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
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
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.
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
schema:
type: string
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
example: 'octopus'
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
- name: emoji_code
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
An encoded version of the unicode codepoint. For most
clients, you won't need this; it's used to handle a rare
corner case when upvoting a unicode emoji reaction added
previously by another user.
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
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
If the existing reaction was added when the Zulip
server was using a previous version of the emoji
data mapping from codepoints to human-readable
names, sending the `emoji_code` in the data for
the original reaction allows the Zulip server to
correctly consider your upvote as an upvote
rather than a reaction with a "diffenent" emoji.
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
schema:
type: string
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
example: '1f419'
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: false
- name: reaction_type
in: query
description: |
api docs: Document API level 2 change in custom emoji.
2020-04-29 06:39:28 +02:00
If the client is upvoting a reaction and wants to specifically add
a vote to an existing reaction, we recommend passing this parameter
using the value the server provided for the existing reaction.
**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 (as `realm_emoji` for custom
emoji).
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
schema:
type: string
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
example: 'unicode_emoji'
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: 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'
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: 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'
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
- name: emoji_name
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
Name of the emoji you want to delete from a reaction.
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
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
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.
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
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
Ignored if emoji_code is also passed.
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
schema:
type: string
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
example: 'octopus'
required: false
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
- name: emoji_code
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
Alternative to emoji_name for expressing which emoji to remove. An
encoded version of the unicode codepoint for the emoji you'd like to
remove from the message.
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
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
Recommended over using `emoji_name` for Zulip apps
because this more robustly handles changes in the mapping
between user-facing names and aliases for emoji (which change from
time to time) and their unicode codepoints.
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
schema:
type: string
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
example: '1f419'
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: false
- name: reaction_type
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
When removing a reaction with a [custom emoji](/help/add-custom-emoji),
set `reaction_type` to `realm_emoji`.
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
schema:
type: string
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
example: 'unicode_emoji'
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: false
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: 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:
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: 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'
users: Refactor get_members_backend endpoint to use get_raw_user_data. Modify the get_raw_user_data method for use by the /users API endpoint and then modify the /users endpoint to use it.
2019-10-20 19:15:44 +02:00
- name: include_custom_profile_fields
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
Set to `true` if the client wants custom profile field data to be
included in the response.
docs: Update API documention to note changes in Zulip 2.1.0.
2020-03-27 02:02:20 +01:00
**Changes**: New in Zulip 2.1.0. Previous versions do no offer these
data via the API.
users: Refactor get_members_backend endpoint to use get_raw_user_data. Modify the get_raw_user_data method for use by the /users API endpoint and then modify the /users endpoint to use it.
2019-10-20 19:15:44 +02:00
schema:
type: boolean
default: false
example: true
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:
type: object
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,
"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,
"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,
"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: 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 "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'
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: include_custom_profile_fields
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 client should pass true if it wants to include custom profile field data.
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: boolean
default: false
example: true
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:
type: object
description: |
A dictionary containing the requested user's details.
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,
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com"
}
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
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
}
patch:
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: 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: string
format: json
example: NewName
required: false
- name: is_admin
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 target user is an administrator.
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: boolean
example: false
required: false
- name: is_guest
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 target user is a guest.
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: boolean
example: true
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 "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"
}
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: 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.
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 "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
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: |
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: 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: |
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: -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:
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 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
users: Send custom profile fields with the /profile endpoint.
2019-10-25 20:28:53 +02:00
supporting markdown, a `rendered_value` key will also be present.
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,
"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: 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: 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
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: |
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
The ID of the last message sent to the topic.
type: number
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 "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.
operationId: zerver.views.streams.list_subscriptions_backend
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
items:
type: object
- 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: 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
- name: principals
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 email addresses of the users that will be subscribed to the
streams specified in the `subscriptions` argument. If not provided, then
the requesting user/bot is subscribed.
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: string
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
default: []
example: ['ZOE@zulip.com']
- 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: 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: 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: zerver.views.streams.update_subscriptions_backend
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: 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
- name: principals
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 email addresses of the users that will be unsubscribed from
the streams specified in the `subscriptions` argument. If not provided,
then the requesting user/bot is unsubscribed.
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
schema:
type: array
items:
type: string
example: ['ZOE@zulip.com']
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: 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: 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 "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.
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,
"author": {
"id": 5,
"email": "iago@zulip.com",
"full_name": "Iago"
}
}
}
}
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
/users/me/subscriptions/properties:
post:
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: 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 "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 "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 "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 "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": {
"author": {
"email": "iago@zulip.com",
"full_name": "Iago",
"id": 5
},
"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: 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.
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: |
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
List of dictionaries describing which external
authentication methods are enabled and their
parameters - most importantly the login url,
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
display_name and display_icon.
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
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: |
An integer to indicate the features added to the server.
The feature level increases monotonically; a value of N
means the server supports all API features introduced
before feature level N. This provides fine-grained
distinctions among development versions in between major
releases.
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: |
Whether usernames should have an email address format. This is important if your server has [LDAP
authentication](https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap-including-active-directory)
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
enabled with a username and password combination.
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: |
The organization's URI.
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: |
The realm's name.
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: |
The URI of the organization's mobile icon (usually a square version of
the logo).
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: 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.
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
schema:
type: string
docs: Make update-notification-settings use curl example system.
2019-10-18 09:00:43 +02:00
format: json
tests: Remove /settings/notifications from buggy endpoints.
2019-10-07 10:18:53 +02:00
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: 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:
type: array
items:
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 list of `stream` objects, which contain a `description`, a `name`,
their `stream_id` and whether they are `invite_only` or not.
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: 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}`
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: zerver.views.streams.deactivate_stream_backend
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: 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}`
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: zerver.views.streams.update_stream_backend
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.
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
schema:
type: string
docs: Make update-stream use curl example system. new_name and description params should be valid JSON strings. The format of these params are marked as json so that the curl example genenrator can convert them into json strings.
2019-10-18 08:47:27 +02:00
format: json
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
example: "This stream is related to football dicsussions."
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.
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
schema:
type: string
docs: Make update-stream use curl example system. new_name and description params should be valid JSON strings. The format of these params are marked as json so that the curl example genenrator can convert them into json strings.
2019-10-18 08:47:27 +02:00
format: json
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
example: "Italy"
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: 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: 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: 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: 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: 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: 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: 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'
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
example: event_types=['message']
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:
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:
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:
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.
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.
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: |
The ID of the group.
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
(`type="stream"`), ignored otherwise. Maximum length of 60
characters.
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: |
The ID of a queue that you registered via `POST /api/v1/register` (see
[Register a queue](/api/register-queue)).
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: |
The name of the stream.
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: |
The user id of the user.
schema:
type: integer
example: 11
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.
**Changes**: New in Zulip 2.2, replacing the previous is_announcement_only
boolean.
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: |
A boolean indicating if the history should be available to newly
subscribed members.
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