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

5641 lines
222 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:
docs: Update URLs to use https://zulip.com. We're migrating to using the cleaner zulip.com domain, which involves changing all of our links from ReadTheDocs and other places to point to the cleaner URL.
2020-06-08 23:04:39 +02:00
url: https://zulip.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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
# Zulip Cloud
- url: "https://{subdomain}.zulipchat.com/api/v1"
variables:
subdomain:
default: example
# Self-hosted
- url: "{server}/api/v1"
variables:
server:
default: https://
# chat.zulip.org
- url: "https://chat.zulip.org/api/v1"
# Development server
- url: "http://localhost:9991/api/v1"
openapi: Specify securityScheme for the API in root level. We used to specify the securityScheme for each REST operation seperately. This is unecessary as the securityScheme can be specified in root level and would be automatically applied to all operations. This also prevents us accidentally not specifying the securityScheme for some operations and was the case for /users/me/subscriptions PATCH endpoint. The root level securityScheme can be also overriden in the operational level when necessary. swagger.io/docs/specification/authentication/#security
2019-12-04 12:27:15 +01:00
security:
- basicAuth: []
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
#######################
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
# Endpoint definitions
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
#######################
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
paths:
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
/fetch_api_key:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: fetch_api_key
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["authentication"]
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
description: |
Given a username and password, fetch the user's API key.
Used to authenticate the mobile and terminal apps when the server
has EmailAuthBackend or LDAPAuthBackend enabled.
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: username
in: query
description: |
The username to be used for authentication (typically, the email
address, but it could be an LDAP username).
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
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
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
description: The credentials needed to use the Zulip API.
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
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/ApiKeyResponse"
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
/dev_fetch_api_key:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: dev_fetch_api_key
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["authentication"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
For easy testing of mobile apps and other clients and against Zulip
development servers, we support fetching a Zulip API key for any user
on the development server without authentication (so that they can
implement analogues of the one-click login process available for Zulip
development servers on the web).
**Note:** This endpoint is only available on Zulip development
servers; for obvious security reasons it will always return an error
in a Zulip production server.
`POST {{ api_url }}/v1/dev_fetch_api_key`
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: username
in: query
description: |
The email address for the user that owns the API key.
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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/ApiKeyResponse"
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
/events:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_events
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
`GET {{ api_url }}/v1/events`
This endpoint allows you to receive new events from
[a registered event queue](/api/register-queue).
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/QueueId"
- name: last_event_id
in: query
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
exactly once.
schema:
type: integer
example: -1
- name: dont_block
in: query
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.
schema:
type: boolean
default: false
example: true
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
events:
type: array
description: |
An array of `event` objects (possibly zero-length if `dont_block` is
set) with IDs newer than `last_event_id`. Event IDs are
guaranteed to be increasing, but they are not guaranteed to be
consecutive.
items:
openapi: Document various events.
2020-07-23 23:39:18 +02:00
oneOf:
- type: object
description: |
Event sent to a user's clients when that user's set of configured
[alert words](/help/add-an-alert-word) have changed.
properties:
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
id:
type: integer
openapi: Document various events.
2020-07-23 23:39:18 +02:00
type:
type: string
enum:
- alert_words
alert_words:
type: array
description: |
Array of strings, each a configured alert word.
items:
type: string
additionalProperties: false
example:
{
"type": "alert_words",
"alert_words": ["alert_word"],
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's display settings
have changed.
properties:
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
id:
type: integer
openapi: Document various events.
2020-07-23 23:39:18 +02:00
type:
type: string
enum:
- update_display_settings
setting_name:
type: string
description: |
Name of the changed display setting.
setting:
description: |
New value of the changed setting.
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
oneOf:
- type: boolean
- type: integer
- type: string
language_name:
description: |
Present only if the setting to be changed is
`default_language`. Contains the name of the
new default language in English.
type: string
openapi: Document various events.
2020-07-23 23:39:18 +02:00
additionalProperties: false
example:
{
"type": "update_display_settings",
"setting_name": "high_contrast_mode",
"setting": false,
}
- type: object
description: |
Event sent to a user's clients when that user's [notification
settings](/api/update-notification-settings) have changed.
properties:
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
id:
type: integer
openapi: Document various events.
2020-07-23 23:39:18 +02:00
type:
type: string
enum:
- update_global_notifications
notification_name:
type: string
description: |
Name of the changed notification setting.
setting:
description: |
New value of the changed setting.
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
oneOf:
- type: boolean
- type: integer
- type: string
openapi: Document various events.
2020-07-23 23:39:18 +02:00
additionalProperties: false
example:
{
"type": "update_global_notifications",
"notification_name": "enable_sounds",
"setting": true,
}
- type: object
description: |
Event sent generally to all users in an organization for changes
in the set of users or those users metadata.
properties:
type:
type: string
enum:
- realm_user
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
id:
type: integer
openapi: Document various events.
2020-07-23 23:39:18 +02:00
op:
type: string
enum:
- update
person:
description: |
Object containing the changed details of the user.
It has multiple forms depending on the value changed.
oneOf:
- type: object
description: |
When a user changes their full name.
properties:
user_id:
type: integer
description: |
The id of modified user.
full_name:
type: string
description: |
The new full name for the user.
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
additionalProperties: false
openapi: Document various events.
2020-07-23 23:39:18 +02:00
- type: object
description: |
When a user changes their avatar.
properties:
user_id:
type: integer
description: |
The id of the user who is affected by this change.
avatar_url:
type: string
description: |
The url of the new avatar URL for the user.
avatar_source:
type: string
description: |
The new avatar data source type for the user.
Value values are `G` (gravatar) and `U` (uploaded by user).
avatar_url_medium:
type: string
description: |
The new medium-size avatar URL for user.
avatar_version:
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
type: integer
openapi: Document various events.
2020-07-23 23:39:18 +02:00
description: |
The version number for the user's avatar. This is useful
for cache-busting.
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
additionalProperties: false
openapi: Document various events.
2020-07-23 23:39:18 +02:00
- type: object
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
additionalProperties: false
openapi: Document various events.
2020-07-23 23:39:18 +02:00
description: |
When a user changes their timezone setting.
properties:
user_id:
type: integer
description: |
The id of modified user.
email:
type: string
description: |
The email of the user.
**Deprecated**: This field will be removed in a future
release as it is redunant with the `user_id`.
deprecated: true
timezone:
type: string
description: |
The new timezone of the user.
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
- type: object
additionalProperties: false
description: |
When the owner of a bot changes.
properties:
user_id:
type: integer
description: |
The id of the user/bot whose owner has changed.
bot_owner_id:
type: integer
description: |
The user id of the new bot owner.
- type: object
additionalProperties: false
description: |
When the role of a user changes.
properties:
user_id:
type: integer
description: |
The id of the user affected by this change.
role:
type: integer
description: |
The new role of the user in integer.
- type: object
additionalProperties: false
description: |
When the delivery email of a user changes.
Note: This event is only visible to admins.
properties:
user_id:
type: integer
description: |
The id of the user affected by this change.
delivery_email:
type: string
description: |
The new delivery email of the user.
- type: object
additionalProperties: false
description: |
When the user updates one of their custom profile
fields.
properties:
user_id:
type: integer
description: |
The id of the user affected by this change.
custom_profile_field:
type: object
additionalProperties: false
description: |
Object containing details about the custom
profile data change.
properties:
id:
type: integer
description: |
The id of the custom profile field which user updated.
value:
type: string
description: |
User's personal value for this custom profile field.
rendered_value:
type: string
description: |
The `value` rendered in HTML. Will only be present for
custom profile field types that support markdown rendering.
This user-generated HTML content should be rendered
using the same CSS and client-side security protections
as are used for message content.
openapi: Document various events.
2020-07-23 23:39:18 +02:00
additionalProperties: false
example:
{
"type": "realm_user",
"op": "update",
"person":
{
"avatar_source": "G",
"avatar_url": "https:\/\/secure.gravatar.com\/avatar\/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=3",
"avatar_url_medium": "https:\/\/secure.gravatar.com\/avatar\/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&s=500&version=3",
"avatar_version": 3,
"user_id": 10,
},
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's stream subscriptions
have changed (either the set of subscriptions or their properties).
properties:
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
id:
type: integer
openapi: Document various events.
2020-07-23 23:39:18 +02:00
type:
type: string
enum:
- subscription
op:
type: string
enum:
- add
subscriptions:
type: array
description: |
A list of dictionaries where each dictionary contains
information about one of the subscribed streams.
items:
$ref: "#/components/schemas/Subscriptions"
additionalProperties: false
example:
{
"type": "subscription",
"op": "add",
"subscriptions":
[
{
"name": "test_stream",
"stream_id": 9,
"description": "",
"rendered_description": "",
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": null,
"message_retention_days": null,
"is_announcement_only": false,
"color": "#76ce90",
"is_muted": false,
"pin_to_top": false,
"audible_notifications": null,
"desktop_notifications": null,
"email_notifications": null,
"push_notifications": null,
"wildcard_mentions_notify": null,
"in_home_view": true,
"email_address": "test_stream.af64447e9e39374841063747ade8e6b0.show-sender@testserver",
"stream_weekly_traffic": null,
"subscribers": [10],
},
],
"id": 0,
}
openapi: Document `message` event.
2020-07-28 00:01:59 +02:00
- type: object
description: |
Event type for messages.
properties:
id:
type: integer
type:
type: string
enum:
- message
message:
$ref: "#/components/schemas/Messages"
flags:
type: array
description: |
The user's [message flags][message-flags] for the message.
items:
type: string
email_notified:
type: boolean
description: |
Whether the user receiving the event has already been
notified via email.
push_notified:
type: boolean
description: |
Whether the user receiving the event has already been
notified via mobile notification.
stream_push_notify:
type: boolean
description: |
Whether the user receiving the event has to be notified
via mobile notification for stream message.
stream_email_notify:
type: boolean
description: |
Whether the user receiving the event has to be notified
via email for stream message.
wildcard_mention_notify:
type: boolean
description: |
Whether the user has to be notified due to wildcard mention.
additionalProperties: false
example:
{
"type": "message",
"message":
{
"id": 31,
"sender_id": 10,
"content": "<p>First message ...<a href=\"user_uploads\/2\/ce\/2Xpnnwgh8JWKxBXtTfD6BHKV\/zulip.txt\">zulip.txt<\/a><\/p>",
"recipient_id": 23,
"timestamp": 1594825416,
"client": "test suite",
"subject": "test",
"topic_links": [],
"is_me_message": false,
"reactions": [],
"submessages": [],
"sender_full_name": "King Hamlet",
"sender_short_name": "hamlet",
"sender_email": "user10@zulip.testserver",
"sender_realm_str": "zulip",
"display_recipient": "Denmark",
"type": "stream",
"stream_id": 1,
"avatar_url": null,
"content_type": "text\/html",
},
"flags": [],
"id": 1,
}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
queue_id:
type: string
description: |
The ID of the registered queue.
- example:
{
js_examples: Migrate and test get_events example. This also adds "queue_id" to the response parameters and in the example for GET /events in zulip.yaml.
2020-06-29 18:14:47 +02:00
"queue_id": "1375801870:2942",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"events":
[
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"id": 0,
"message":
{
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
"content": "I come not, friends, to steal away your hearts.",
"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",
"topic": "Castle",
"topic_links": [],
"timestamp": 1375978403,
"type": "stream",
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"type": "message",
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"id": 1,
"message":
{
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
"content": "With mirth and laughter let old wrinkles come.",
"content_type": "text/x-markdown",
"display_recipient":
[
{
"email": "hamlet@example.com",
"full_name": "Hamlet of Denmark",
"id": 31572,
},
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
],
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"id": 12345679,
"recipient_id": 18391,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"subject": "",
"topic_links": [],
"timestamp": 1375978404,
"type": "private",
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"type": "message",
},
],
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
"msg": "",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/BadEventQueueIdError"
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
delete:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: delete_queue
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Delete a previously registered queue.
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
`DELETE {{ api_url }}/v1/events`
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/QueueId"
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
"400":
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
description: Bad request.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/BadEventQueueIdError"
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
/get_stream_id:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_stream_id
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Get the unique ID of a given stream.
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
`GET {{ api_url }}/v1/get_stream_id`
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/Stream"
required: true
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
stream_id:
type: integer
description: |
The ID of the given stream.
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"msg": "", "result": "success", "stream_id": 15}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
- example:
{
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
"code": "BAD_REQUEST",
"msg": "Invalid stream name 'nonexistent'",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
/mark_all_as_read:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: mark_all_as_read
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Marks all of the current user's unread messages as read.
`POST {{ api_url }}/v1/mark_all_as_read`
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
/mark_stream_as_read:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: mark_stream_as_read
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Mark all the unread messages in a stream as read.
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/StreamIdInQuery"
required: true
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
/mark_topic_as_read:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: mark_topic_as_read
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Mark all the unread messages in a topic as read.
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/StreamIdInQuery"
required: true
- name: topic_name
in: query
description: |
The name of the topic whose messages should be marked as read.
schema:
type: string
example: new coffee machine
required: true
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
openapi: Document GET /attachments endpoint.
2020-03-20 23:23:25 +01:00
/attachments:
get:
operationId: get_attachments
tags: ["users"]
description: |
Fetch metadata on files uploaded by the requesting user.
`GET {{ api_url }}/v1/attachments`
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
openapi: Document GET /attachments endpoint.
2020-03-20 23:23:25 +01:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
attachments:
type: array
description: |
A list of `attachment` objects, each containing
details about a file uploaded by the user.
items:
type: object
additionalProperties: false
properties:
id:
type: integer
description: |
The unique ID for the attachment.
name:
type: string
description: |
Name of the uploaded file.
path_id:
type: string
description: |
A representation of the path of the file within the
repository of user-uploaded files. If the `path_id` of a
file is `{realm_id}/ab/cdef/temp_file.py`, its URL will be:
`{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`.
size:
type: integer
description: |
Size of the file in bytes.
create_time:
type: integer
description: |
Time when the attachment was uploaded as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
**Changes**: Changed in Zulip 2.2 (feature level 22). This field was
previously a floating point number.
messages:
type: array
description: |
Contains basic details on any Zulip messages that have been
sent referencing this [uploaded file](/api/upload-file).
This includes messages sent by any user in the Zulip
organization who sent a message containing a link to the
uploaded file.
items:
type: object
additionalProperties: false
properties:
date_sent:
type: integer
description: |
Time when the message was sent as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
**Changes**: Changed in Zulip 2.2 (feature level 22). This
field was previously strangely called `name` and was a floating
point number.
id:
type: integer
description: |
The unique message ID. Messages should always be
displayed sorted by ID.
upload_space_used:
type: integer
description: |
The total size of all files uploaded by in the organization,
in bytes.
- example:
{
openapi: Document GET /attachments endpoint.
2020-03-20 23:23:25 +01:00
"result": "success",
"msg": "",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"attachments":
[
openapi: Document GET /attachments endpoint.
2020-03-20 23:23:25 +01:00
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"id": 1,
"name": "166050.jpg",
"path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg",
"size": 571946,
"create_time": 1588145417000,
"messages":
[
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"id": 102, "date_sent": 1588145424000},
{"id": 103, "date_sent": 1588145448000},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
],
},
],
"upload_space_used": 571946,
}
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
/messages:
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_messages
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Fetch message history from a Zulip server.
`GET {{ api_url }}/v1/messages`
This `GET /api/v1/messages` endpoint is the primary way to fetch
message history from a Zulip server. It is useful both for Zulip
clients (e.g. the web, desktop, mobile, and terminal clients) as well
as bots, API clients, backup scripts, etc.
By specifying a [narrow filter](/api/construct-narrow), you can use
this endpoint to fetch the messages matching any search query that is
supported by Zulip's powerful full-text search backend.
When a narrow is not specified, it can be used to fetch a user's
message history (We recommend paginating to 1000 messages at a time).
In either case, you specify an `anchor` message (or ask the server to
calculate the first unread message for you and use that as the
anchor), as well as a number of messages before and after the anchor
message. The server returns those messages, sorted by message ID, as
well as some metadata that makes it easy for a client to determine
whether there are more messages matching the query that were not
returned due to the `num_before` and `num_after` limits.
We recommend using `num_before <= 1000` and `num_after <= 1000` to
avoid generating very large HTTP responses. A maximum of 5000 messages
can be obtained per request; attempting to exceed this will result in an
error.
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: anchor
in: query
description: |
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:
* `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.
The special values of `'newest'` and `'oldest'` are also supported
for anchoring the query at the most recent or oldest messages.
**Changes**: String values are new in Zulip 3.0 (feature level 1). The
`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).
schema:
oneOf:
- type: string
- type: integer
example: 42
- name: num_before
in: query
description: |
The number of messages with IDs less than the anchor to retrieve.
schema:
type: integer
minimum: 0
example: 4
required: true
- name: num_after
in: query
description: |
The number of messages with IDs greater than the anchor to retrieve.
schema:
type: integer
minimum: 0
example: 8
required: true
- name: narrow
in: query
description: |
The narrow where you want to fetch the messages from. See how to
[construct a narrow](/api/construct-narrow).
content:
application/json:
schema:
type: array
items:
type: object
default: []
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
example: [{"operand": "Denmark", "operator": "stream"}]
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/ClientGravatar"
- name: apply_markdown
in: query
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.
schema:
type: boolean
default: true
example: false
- name: use_first_unread_anchor
in: query
deprecated: true
description: |
Legacy way to specify `anchor="first_unread"` in Zulip 2.1.x and older.
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
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
Whether to use the (computed by the server) first unread message
matching the narrow as the `anchor`. Mutually exclusive with `anchor`.
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
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
**Changes**: Deprecated in Zulip 3.0, 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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
anchor:
type: integer
description: |
The same `anchor` specified in the request (or the computed one, if
`use_first_unread_anchor` is `true`).
found_newest:
type: boolean
description: |
Whether the `messages` list includes the very newest messages matching
the narrow (used by clients that paginate their requests to decide
whether there are more messages to fetch).
found_oldest:
type: boolean
description: |
Whether the `messages` list includes the very oldest messages matching
the narrow (used by clients that paginate their requests to decide
whether there are more messages to fetch).
found_anchor:
type: boolean
description: |
Whether the anchor message is included in the
response. If the message with the ID specified
in the request does not exist or did not match
the narrow, this will be false.
history_limited:
type: boolean
description: |
Whether the message history was limited due to
plan restrictions. This flag is set to `true`
only when the oldest messages(`found_oldest`)
matching the narrow is fetched.
messages:
type: array
description: |
an array of `message` objects, each containing the following
fields:
items:
openapi: Edit `Messages` component to match the `message` event object. The `Messages` schema present in `#/components/schemas` was a combination of all keys possible in any message object used in Zulip. Edit it so that the original `Messages` contains just the keys present in the `message` event. Also make another schema `GetMessages` which adds a few other keys which are received when using `GET /messages`. The message object in the `/zulip-outgoing-webhook` has also been modified and corrected.
2020-07-20 17:28:20 +02:00
$ref: "#/components/schemas/GetMessages"
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- example:
{
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
"anchor": 21,
"found_newest": true,
"found_anchor": true,
"result": "success",
"msg": "",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"messages":
[
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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":
[
{
"id": 4,
"is_mirror_dummy": false,
"email": "hamlet@zulip.com",
"full_name": "King Hamlet",
},
{
"id": 5,
"is_mirror_dummy": false,
"email": "iago@zulip.com",
"full_name": "Iago",
},
{
"id": 8,
"is_mirror_dummy": false,
"email": "prospero@zulip.com",
"full_name": "Prospero from The Tempest",
},
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
],
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"content_type": "text/html",
"is_me_message": false,
"timestamp": 1527921326,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 27,
"topic_links": [],
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": [],
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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,
"timestamp": 1527939746,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 20,
"topic_links": [],
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": [],
},
],
}
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: send_message
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Send a stream or a private message.
`POST {{ api_url }}/v1/messages`
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: type
in: query
description: |
The type of message to be sent. `private` for a private message and
`stream` for a stream message.
schema:
type: string
enum:
- private
- stream
example: private
required: true
- name: to
in: query
description: |
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
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
**Changes**: Support for using user/stream IDs was added in Zulip 2.0.0.
content:
application/json:
schema:
type: array
items:
type: integer
example: [9, 10]
required: true
- $ref: "#/components/parameters/RequiredContent"
- $ref: "#/components/parameters/Topic"
- name: queue_id
in: query
schema:
type: string
description: |
For clients supporting
[local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo),
the [event queue](/api/register-queue)
ID for the client. If passed, `local_id` is required. If the message is
successfully sent, the server will include `local_id` in the `message` event
that the client with this `queue_id` will receive notifying it of the new message
via [`GET /events`](/api/get-events). This lets the client know unambiguously
that it should replace the locally echoed message, rather than adding this new
message (which would be correct if the user had sent the new message from another
device).
example: "1593114627:0"
- name: local_id
in: query
schema:
type: string
description: |
For clients supporting local echo, a unique string-format identifier
chosen freely by the client; the server will pass it back to the client without
inspecting it, as described in the `queue_id` description.
example: "100.01"
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
id:
type: integer
description: |
The unique ID assigned to the sent message.
deliver_at:
type: string
description: |
Present for scheduled messages, encodes the time when the message will
be sent. Note that scheduled messages ("Send later") is a beta API and
may change before it's a finished feature.
example: "2020-06-24 11:19:54.337533+00:00"
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"msg": "", "id": 42, "result": "success"}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/NonExistingStreamError"
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid email 'eeshan@zulip.com'",
"result": "error",
}
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
/messages/{message_id}/history:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_message_history
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Fetch the message edit history of a previously edited message.
`GET {{ api_url }}/v1/messages/{message_id}/history`
Note that edit history may be disabled in some organizations; see the
[Zulip Help Center documentation on editing messages][edit-settings].
[edit-settings]: /help/view-a-messages-edit-history
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
message_history:
type: array
items:
type: object
additionalProperties: false
properties:
topic:
type: string
description: |
the topic for the message.
prev_topic:
type: string
description: |
the topic for the message before being edited.
content:
type: string
description: |
the body of the message.
rendered_content:
type: string
description: |
the already rendered, HTML version of `content`.
prev_content:
type: string
description: |
the body of the message before being edited.
prev_rendered_content:
type: string
description: |
the already rendered, HTML version of
`prev_content`.
user_id:
type: integer
description: |
the ID of the user that made the edit.
content_html_diff:
type: string
description: |
an HTML diff between this version of the message
and the previous one.
timestamp:
type: integer
description: |
the UNIX timestamp for this edit.
description: |
A chronologically sorted array of `snapshot`
objects, each one with the values of the
message after the edit.
- example:
{
"message_history":
[
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"content": "Hello!",
"topic": "party at my houz",
"rendered_content": "<p>Hello!</p>",
"timestamp": 1530129122,
"user_id": 5,
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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,
},
],
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
"msg": "",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "success",
}
"400":
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
description: Bad request.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/InvalidMessageError"
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
/messages/flags:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_message_flags
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
api docs: Improve headings and organization for endpoints. Mostly, this is a change in ordering to make more sense, but we also fix several names that were clearly confusing. We restore the convention that each endpoint has the same title at the top of the page as what we have in the sidebar menu, which appears to have been violated in many recent updates to API documentation.
2020-06-19 07:30:42 +02:00
Add or remove personal message flags like `read` and `starred`
on a collection of message IDs.
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
openapi: Make api-docs filename match with operationIds. api docs filenames are basically the operationId of their endpoint in zulip.yaml with `_` replaced by `-`. But some operationIds have changed, so change the affected filenames. Make changes in other files accordingly.
2020-06-11 14:44:00 +02:00
[special endpoints for marking message as read in bulk](/api/mark-all-as-read).
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: messages
in: query
description: |
An array containing the IDs of the target messages.
content:
application/json:
schema:
type: array
items:
type: integer
example: [4, 8, 15]
required: true
- name: op
in: query
description: |
Whether to `add` the flag or `remove` it.
schema:
type: string
enum:
- add
- remove
example: add
required: true
- name: flag
in: query
description: |
The flag that should be added/removed.
schema:
type: string
example: read
required: true
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
messages:
type: array
items:
type: integer
description: |
An array with the IDs of the modified messages.
- example:
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"msg": "", "messages": [4, 18, 15], "result": "success"}
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
/messages/render:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: render_message
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Render a message to HTML.
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
`POST {{ api_url }}/v1/messages/render`
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/RequiredContent"
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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
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
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
rendered:
type: string
description: |
The rendered HTML.
- example:
{
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
"msg": "",
"rendered": "<p><strong>foo</strong></p>",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "success",
}
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
/messages/{message_id}/reactions:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: add_reaction
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Create markdown extension for rendering endpoint descriptions. Add function in openapi.py to access endpoint descriptions written in zulip.yaml. Use this function for creating a markdown extension for rendering endpoint descriptions written in zulip.yaml. We use this extension for a single endpoint to get test coverage.
2020-04-28 12:13:46 +02:00
Add an [emoji reaction](/help/emoji-reactions) to a message.
`POST {{ api_url }}/v1/messages/{message_id}/reactions`
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/MessageId"
- $ref: "#/components/parameters/EmojiName"
required: true
- $ref: "#/components/parameters/EmojiCode"
- $ref: "#/components/parameters/ReactionType"
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
$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
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"400":
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
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
- 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",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"code": "BAD_REQUEST",
}
api: Document POST ../messages/{message_id}/reactions endpoint. This refactors add_reaction in python_examples.py to use the openapi_test_function decorator and validate result with validate_against_openapi_schema. Minor changes have been made to the OpenAPI format data for /messages/{message_id}/reactions endpoint. This also adds add-emoji.md to templates/zerver/api and adds add-emoji to rest-endpoints.md (templates/zerver/help/include).
2020-02-29 15:02:34 +01:00
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: remove_reaction
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Remove an [emoji reaction](/help/emoji-reactions) from a message.
`DELETE {{ api_url }}/v1/messages/{message_id}/reactions`
docs: Add OpenAPI data for `/messages/{message_id}/reactions`. This change adds the OpenAPI data needed to document the POST and DELETE methods associated with this endpoint. Descriptions edited slightly by tabbott.
2019-09-24 20:46:14 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/MessageId"
- $ref: "#/components/parameters/EmojiName"
required: false
- $ref: "#/components/parameters/EmojiCode"
- $ref: "#/components/parameters/ReactionType"
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
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
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
- 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)",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"code": "BAD_REQUEST",
}
api docs: Document GET /messages/matches_narrow endpoint. With extensive tweaks from tabbott to provide clear explanations for the features.
2020-03-15 14:16:02 +01:00
/messages/matches_narrow:
get:
operationId: check_messages_match_narrow
tags: ["messages"]
description: |
Check whether a set of messages match a [narrow](/api/construct-narrow).
`GET {{ api_url }}/v1/messages/matches_narrow`
For many common narrows (E.g. a topic), clients can write an
efficient client-side check to determine whether a
newly arrived message belongs in the view.
This endpoint is designed to allow clients to handle more complex narrows
for which the client does not (or in the case of full-text search,
cannot) implement this check.
The format of the `match_subject` and `match_content` objects is designed to match
those of `GET /messages`, so that a client can splice these fields into a
`message` object received from `GET /events` and end up with an extended message
object identical to how a `GET /messages` for the current narrow would have
returned the message.
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: msg_ids
in: query
description: List of IDs for the messages to check.
content:
application/json:
schema:
type: array
items:
type: integer
example: [31, 32]
required: true
- name: narrow
in: query
description:
A structure defining the narrow to check against. See how to
[construct a narrow](/api/construct-narrow).
content:
application/json:
schema:
type: array
items:
type: object
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
example: [{"operator": "has", "operand": "link"}]
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
required: true
api docs: Document GET /messages/matches_narrow endpoint. With extensive tweaks from tabbott to provide clear explanations for the features.
2020-03-15 14:16:02 +01:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document GET /messages/matches_narrow endpoint. With extensive tweaks from tabbott to provide clear explanations for the features.
2020-03-15 14:16:02 +01:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
messages:
api docs: Document GET /messages/matches_narrow endpoint. With extensive tweaks from tabbott to provide clear explanations for the features.
2020-03-15 14:16:02 +01:00
type: object
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
A dictionary with a key for each queried message that matches the narrow,
with message IDs as keys and search rendering data as values.
additionalProperties:
type: object
additionalProperties: false
properties:
match_content:
type: string
description: |
HTML content of a queried message that matches the narrow. If the
narrow is a search narrow, `<span class="highlight">` elements
will be included, wrapping the matches for the search keywords.
match_subject:
type: string
description: |
HTML-escaped topic of a queried message that matches the narrow. If the
narrow is a search narrow, `<span class="highlight">` elements
will be included wrapping the matches for the search keywords.
description: |
The ID of the message that matches the narrow. No record will be returned
for queried messages that do not match the narrow.
- example:
{
"result": "success",
"msg": "",
"messages":
{
"31":
{
"match_content": '<p><a href="http://foo.com" target="_blank" title="http://foo.com">http://foo.com</a></p>',
"match_subject": "test_topic",
},
},
api docs: Document GET /messages/matches_narrow endpoint. With extensive tweaks from tabbott to provide clear explanations for the features.
2020-03-15 14:16:02 +01:00
}
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
/messages/{message_id}:
get:
operationId: get_raw_message
tags: ["messages"]
description: |
Get the raw content of a message.
`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).
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/MessageId"
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
raw_content:
type: string
description: |
The raw content of the message.
- example:
{
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
"raw_content": "**Don't** forget your towel!",
"result": "success",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"msg": "",
}
"400":
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
description: Bad request.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/InvalidMessageError"
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
patch:
operationId: update_message
tags: ["messages"]
description: |
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.
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/MessageId"
- $ref: "#/components/parameters/Topic"
- name: propagate_mode
in: query
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.
schema:
type: string
enum:
- change_one
- change_later
- change_all
default: change_one
example: change_all
- name: send_notification_to_old_thread
in: query
description: |
Whether to send breadcrumb message to the old thread to
notify users where the messages were moved to.
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
**Changes**: New in Zulip 3.0 (feature level 9).
schema:
type: boolean
default: true
example: true
- name: send_notification_to_new_thread
in: query
description: |
Whether to send a notification message to the new thread to
notify users where the messages came from.
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
**Changes**: New in Zulip 3.0 (feature level 9).
schema:
type: boolean
default: true
example: true
- $ref: "#/components/parameters/OptionalContent"
- $ref: "#/components/parameters/StreamIdInQuery"
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
"400":
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
- 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
- example:
{
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
"code": "BAD_REQUEST",
"msg": "You don't have permission to edit this message",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
delete:
operationId: delete_message
tags: ["messages"]
description: |
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.
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/MessageId"
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
"400":
openapi: Move `/messages/{message_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/messages/{message_id}` can match with `messages/matches_narrow`. So change the position of of `message/{message_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 17:35:02 +02:00
description: Bad request.
content:
application/json:
schema:
oneOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $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: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
/user_uploads:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: upload_file
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Upload a single file and get the corresponding URI.
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
`POST {{ api_url }}/v1/user_uploads`
Initially, only you will be able to access the link. To share the
uploaded file, you'll need to [send a message][send-message]
containing the resulting link. Users who can already access the link
can reshare it with other users by sending additional Zulip messages
containing the link.
[uploaded-files]: /help/manage-your-uploaded-files
[send-message]: /api/send-message
api docs: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
requestBody:
content:
multipart/form-data:
schema:
properties:
filename:
type: string
format: binary
docs: Add curl example to upload-file.
2019-10-16 13:11:07 +02:00
example: /path/to/file
api docs: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
uri:
type: string
description: |
The URI of the uploaded file.
- example:
{
api docs: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
"msg": "",
"result": "success",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt",
}
upload: Support requesting a temporary unauthenticated URL. This is be useful for the mobile and desktop apps to hand an uploaded file off to the system browser so that it can render PDFs (Etc.). The S3 backend implementation is simple; for the local upload backend, we use Django's signing feature to simulate the same sort of 60-second lifetime token. Co-Author-By: Mateusz Mandera <mateusz.mandera@protonmail.com>
2020-04-08 00:27:24 +02:00
/user_uploads/{realm_id_str}/{filename}:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_file_temporary_url
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["messages"]
upload: Support requesting a temporary unauthenticated URL. This is be useful for the mobile and desktop apps to hand an uploaded file off to the system browser so that it can render PDFs (Etc.). The S3 backend implementation is simple; for the local upload backend, we use Django's signing feature to simulate the same sort of 60-second lifetime token. Co-Author-By: Mateusz Mandera <mateusz.mandera@protonmail.com>
2020-04-08 00:27:24 +02:00
description: |
Get a temporary URL for access to the file that doesn't require authentication.
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- 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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $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:
{
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
"msg": "",
"result": "success",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55",
}
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
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
/users:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_users
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Retrieve details on all users in the organization. Optionally
includes values of [custom profile field](/help/add-custom-profile-fields).
`GET {{ api_url }}/v1/users`
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/ClientGravatar"
- $ref: "#/components/parameters/IncludeCustomProfileFields"
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
members:
type: array
description: |
A list of `user` objects, each containing details about a user in the
organization.
items:
$ref: "#/components/schemas/User"
- example:
{
"msg": "",
"result": "success",
"members":
[
{
"is_active": true,
"email": "AARON@zulip.com",
"is_admin": false,
"is_owner": 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":
{
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"4": {"value": "vim"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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>",
},
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"5": {"value": "1900-1-1"},
"7": {"value": "[11]"},
"6": {"value": "https://blog.zulig.org"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"1":
{
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>",
},
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"8": {"value": "zulipbot"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"3":
{
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate",
},
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
},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
"is_owner": 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,
"is_owner": false,
"user_id": 23,
"bot_type": 1,
"timezone": "",
"is_bot": true,
},
],
}
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: create_user
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Parse {!api-admin-only.md!} in OpenAPI markdown extension. Currently, the OpenAPI extension for rendering description in docs cannot parse {!api-admin-only.md!}. Edit order of markdown extensions in app_filters.py so that rendering of OpenAPI elements takes place before substitution of files using `include`.
2020-05-30 01:36:57 +02:00
{!api-admin-only.md!}
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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: email
in: query
description: |
The email address of the new user.
schema:
type: string
example: username@example.com
required: true
- name: password
in: query
description: |
The password of the new user.
schema:
type: string
example: abcd1234
required: true
- name: full_name
in: query
description: |
The full name of the new user.
schema:
type: string
example: New User
required: true
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
"400":
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
- example:
{
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
"msg": "Email 'newbie@zulip.com' already in use",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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
openapi: Add OpenAPI data for /users/{user_id}/reactivate.
2020-05-16 21:51:26 +02:00
/users/{user_id}/reactivate:
post:
openapi: Add tests for checking presence of various attributes. The swagger validator is a basic tool to check whether our openapi specification file follows the basic syntax. But to ensure that our zulip.yaml file is not only syntactically compatible but also describes our API well, we need to add custom tests. This commit currently checks whether each endpoint has an `operationId` and a valid tag. It also makes it easier to check for custom rules in the future.
2020-05-20 19:53:41 +02:00
operationId: reactivate_user
tags: ["users"]
openapi: Add OpenAPI data for /users/{user_id}/reactivate.
2020-05-16 21:51:26 +02:00
description: |
openapi: Parse {!api-admin-only.md!} in OpenAPI markdown extension. Currently, the OpenAPI extension for rendering description in docs cannot parse {!api-admin-only.md!}. Edit order of markdown extensions in app_filters.py so that rendering of OpenAPI elements takes place before substitution of files using `include`.
2020-05-30 01:36:57 +02:00
{!api-admin-only.md!}
openapi: Add OpenAPI data for /users/{user_id}/reactivate.
2020-05-16 21:51:26 +02:00
[Reactivates a
docs: Update URLs to use https://zulip.com. We're migrating to using the cleaner zulip.com domain, which involves changing all of our links from ReadTheDocs and other places to point to the cleaner URL.
2020-06-08 23:04:39 +02:00
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
openapi: Add OpenAPI data for /users/{user_id}/reactivate.
2020-05-16 21:51:26 +02:00
given their user ID.
`POST {{ api_url }}/v1/users/{user_id}/reactivate`
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/UserId"
openapi: Add OpenAPI data for /users/{user_id}/reactivate.
2020-05-16 21:51:26 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
openapi: Add OpenAPI data for /users/{user_id}/reactivate.
2020-05-16 21:51:26 +02:00
description: Success
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"msg": "", "result": "success"}
openapi: Add OpenAPI data for /users/{user_id}/reactivate.
2020-05-16 21:51:26 +02:00
api docs: Document GET /users/<email>/presence. Tweaked by tabbott to describe more clearly what this is for.
2018-08-07 17:52:03 +02:00
/users/{email}/presence:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_user_presence
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Get the presence status for a specific user.
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
This endpoint is most useful for embedding data about a user's
presence status in other sites (E.g. an employee directory). Full
Zulip clients like mobile/desktop apps will want to use the main
presence endpoint, which returns data for all active users in the
organization, instead.
`GET {{ api_url }}/v1/users/{email}/presence`
See
[Zulip's developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/presence.html)
for details on the data model for presence in Zulip.
api docs: Document GET /users/<email>/presence. Tweaked by tabbott to describe more clearly what this is for.
2018-08-07 17:52:03 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: email
in: path
description: |
The email address of the user whose presence you want to fetch.
schema:
type: string
example: iago@zulip.com
required: true
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
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
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
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
presence:
openapi_responses: Fix get_user_presence.
2020-05-27 14:01:20 +02:00
type: object
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
An object containing the presence details for every client the user has
logged into.
additionalProperties:
type: object
additionalProperties: false
properties:
timestamp:
type: integer
description: |
when this update was received; if the timestamp
is more than a few minutes in the past, the user is offline.
status:
type: string
description: |
either `active` or `idle`: whether the user had
recently interacted with Zulip at the time in the timestamp
(this distinguishes orange vs. green dots in the Zulip web
UI; orange/idle means we don't know whether the user is
actually at their computer or just left the Zulip app open
on their desktop).
description: |
`{client_name}` or `aggregated`: the keys for these objects are
the names of the different clients where this user is logged in,
like `website`, `ZulipDesktop`, `ZulipTerminal`, or
`ZulipMobile`. There is also an `aggregated` key, which matches
the contents of the object that has been updated most
recently. For most applications, you'll just want to look at the
`aggregated` key.
- example:
{
"presence":
{
"website":
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"timestamp": 1532697622, "status": "active"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"ZulipMobile":
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"timestamp": 1522687421, "status": "active"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"aggregated":
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"timestamp": 1532697622, "status": "active"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
},
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
"result": "success",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"msg": "",
}
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
/users/me:
get:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: get_own_user
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Get basic data about the user/bot that requests this endpoint.
`GET {{ api_url }}/v1/users/me`
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
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
description: Success
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
avatar_url:
type: string
description: |
URL for the user's avatar.
users: Refactor get_profile_backend to be based on format_user_row. This commit changes get_profile_backend to be based on format_user_row such that it's a superset of the fields for our other endpoints for getting data on a user. To be clear, this does not removes any of the exisiting fields, that were returned by this endpoint. This change adds some fields to the User object returned by the endpoint. API docs are updated accordingly for the added fields.
2020-06-08 00:29:47 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
**Changes**: New in Zulip 2.1.0.
example: "x"
avatar_version:
type: integer
description: |
Version for the the user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: 1
email:
type: string
description: |
Email of the requesting user.
example: "iago@zulip.com"
full_name:
type: string
description: |
Full name of the requesting user.
example: "Iago"
is_admin:
type: boolean
description: |
A boolean indicating if the requesting user is an admin.
example: true
is_owner:
type: boolean
description: |
A boolean indicating if the requesting user is
an organization owner.
**Changes**: New in Zulip 3.0 (feature level 8).
example: false
is_guest:
type: boolean
description: |
A boolean indicating if the requesting user is a guest.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: false
is_bot:
type: boolean
description: |
A boolean indicating if the requesting user is a bot.
example: false
is_active:
type: boolean
description: |
A boolean specifying whether the user account has been deactivated.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: true
timezone:
type: string
description: |
The time zone of the user.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: ""
date_joined:
type: string
description: |
The time the user account was created.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: "2019-10-20T07:50:53.728864+00:00"
max_message_id:
type: integer
deprecated: true
description: |
The integer ID of the last message received by your account.
**Deprecated**. We plan to remove this in favor of recommending
using `GET /messages` with `anchor="newest"`.
example: 30
user_id:
type: integer
description: |
The user's ID.
example: 1
delivery_email:
type: string
description: |
The user's real email address. This field is present only if
[email address visibility](/help/restrict-visibility-of-email-addresses) is
limited and you are an administrator with access to real email addresses
under the configured policy.
profile_data:
$ref: "#/components/schemas/profile_data"
- 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",
users: Refactor get_profile_backend to be based on format_user_row. This commit changes get_profile_backend to be based on format_user_row such that it's a superset of the fields for our other endpoints for getting data on a user. To be clear, this does not removes any of the exisiting fields, that were returned by this endpoint. This change adds some fields to the User object returned by the endpoint. API docs are updated accordingly for the added fields.
2020-06-08 00:29:47 +02:00
"avatar_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
"email": "iago@zulip.com",
"full_name": "Iago",
"is_admin": true,
users: Add is_owner field to user objects returned by get endpoints. This commit adds 'is_owner' field to the user object returned by '/users', 'users/{user_id}', and '/users/me' endpoints.
2020-06-01 21:47:18 +02:00
"is_owner": false,
users: Refactor get_profile_backend to be based on format_user_row. This commit changes get_profile_backend to be based on format_user_row such that it's a superset of the fields for our other endpoints for getting data on a user. To be clear, this does not removes any of the exisiting fields, that were returned by this endpoint. This change adds some fields to the User object returned by the endpoint. API docs are updated accordingly for the added fields.
2020-06-08 00:29:47 +02:00
"is_guest": false,
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
"is_bot": false,
users: Refactor get_profile_backend to be based on format_user_row. This commit changes get_profile_backend to be based on format_user_row such that it's a superset of the fields for our other endpoints for getting data on a user. To be clear, this does not removes any of the exisiting fields, that were returned by this endpoint. This change adds some fields to the User object returned by the endpoint. API docs are updated accordingly for the added fields.
2020-06-08 00:29:47 +02:00
"is_active": true,
"timezone": "",
"date_joined": "2019-10-20T07:50:53.728864+00:00",
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
"max_message_id": 30,
"msg": "",
"result": "success",
users: Send custom profile fields with the /profile endpoint.
2019-10-25 20:28:53 +02:00
"user_id": 5,
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"profile_data":
{
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"5": {"value": "2000-1-1"},
"4": {"value": "emacs"},
"7": {"value": "[10]"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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.",
},
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"8": {"value": "zulip"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"3":
{
"value": "Apples",
"rendered_value": "<p>Apples</p>",
},
"6":
{
"value": "https://zulip.readthedocs.io/en/latest/",
},
},
}
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: deactivate_my_account
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Delete the requesting user from the realm.
openapi: Remove /users/me from pending endpoints. This commit progress our efforts to reduce pending_endpoints as well as to migrate away from templates/zerver/api/fixtures and towards our OpenAPI documentation. Similar to commit d62b75fc.
2019-08-04 13:08:36 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
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
description: Bad Request
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"msg": "", "result": "success"}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"400":
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
description: Bad Request
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
- example:
{
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
"msg": "Cannot deactivate the only organization administrator",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
/users/me/{stream_id}/topics:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_stream_topics
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Get all the topics in a specific stream
`GET {{ api_url }}/v1/users/me/{stream_id}/topics`
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
topics:
type: array
description: |
An array of `topic` objects.
items:
type: object
additionalProperties: false
properties:
max_id:
description: |
The message ID of the last message sent to this topic.
type: integer
name:
description: |
The name of the topic.
type: string
- example:
{
api docs: Fix indentation.
2018-06-06 18:17:58 +02:00
"msg": "",
"result": "success",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"topics":
[
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"max_id": 26, "name": "Denmark3"},
{"max_id": 23, "name": "Denmark1"},
{"max_id": 6, "name": "Denmark2"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
],
}
"400":
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $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",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
/users/me/subscriptions:
openapi: Remove /users/me/subscriptions from pending_endpoints. In commit 7c71e98, we added a special exception for the /users/me/subscriptions endpoint in the automatic validation test. By adding some extra documentation, we now remove this extra code, as well as the endpoint from the list of pending endpoints.
2019-07-19 07:02:10 +02:00
get:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: get_subscriptions
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Get all streams that the user is subscribed to.
`GET {{ api_url }}/v1/users/me/subscriptions`
openapi: Migrate remaining properties from zulip-2.0.yaml to zulip.yaml. This moves all useful work from the temporary/testing file zulip-2.0.yaml to zulip.yaml, allowing us to remove the old file.
2020-03-08 18:06:11 +01:00
# operationId can be used to record which view function
# corresponds to an endpoint. TODO: Add these for more
# endpoints, and perhaps use this to provide links to implementations.
subscriptions: Avoid sending unneeded subscriber information. The `users/me/subscriptions` endpoint accidentally started returning subscriber information for each stream. This is convenient, but unnecessarily costly for those clients which either don't need it (most API apps) or already acquire this information via /register (including Zulip's apps). This change removes that data set from the default response. Clients which had come to rely on it, or would like to rely on it in future, may still access it via an additional documented API parameter. Fixes #12917.
2019-08-08 21:58:38 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
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
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
# TODO: Is this the best way to declare required elements in 200 responses?
- required:
- subscriptions
- properties:
subscriptions:
type: array
description: |
A list of dictionaries where each dictionary contains
information about one of the subscribed streams.
items:
openapi: Move `subscriptions` schema to the components section. The `subscriptions` has use in multiple endpoints and hence instead of redefining it at every point move it to the the components section for easier reuse.
2020-07-20 13:25:52 +02:00
$ref: "#/components/schemas/Subscriptions"
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- example:
{
"msg": "",
"result": "success",
"subscriptions":
[
{
"audible_notifications": true,
"color": "#e79ab5",
"description": "A Scandinavian country",
"desktop_notifications": true,
"email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981",
"is_muted": false,
"invite_only": false,
"name": "Denmark",
"pin_to_top": false,
"push_notifications": false,
"stream_id": 1,
"subscribers": [7, 10, 11, 12, 14],
},
{
"audible_notifications": true,
"color": "#e79ab5",
"description": "Located in the United Kingdom",
"desktop_notifications": true,
"email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981",
"is_muted": false,
"invite_only": false,
"name": "Scotland",
"pin_to_top": false,
"push_notifications": false,
"stream_id": 3,
"subscribers": [7, 11, 12, 14],
},
],
}
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: subscribe
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Subscribe one or more users to one or more streams.
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
`POST {{ api_url }}/v1/users/me/subscriptions`
If any of the specified streams do not exist, they are automatically
api docs: Correct errors in the stream creation documentation. * Reordered the settings relevant without stream creation to the top. * Removed useless/misleading defaults for optional parameters. * Clarified description of the announce and authorization_errors_fatal settings. * Clarified that `invite_only` only applies for stream creation. (It's annoying to do so for its friends because they are including common description content and OpenAPI doesn't have a way to have extra content in a place you included something) Fixes #14705.
2020-06-25 23:34:10 +02:00
created. The initial [stream settings](/api/update-stream) will be determined
by the optional parameters like `invite_only` detailed below.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: subscriptions
in: query
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.
content:
application/json:
schema:
type: array
items:
type: object
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
example: [{"name": "Verona", "description": "Italian City"}]
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
required: true
- $ref: "#/components/parameters/Principals"
- name: authorization_errors_fatal
in: query
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 response will be a 200 and any streams
where the request encountered an authorization error will be listed
in the `unauthorized` key.
schema:
type: boolean
default: true
example: false
- name: announce
in: query
description: |
If one of the streams specified did not exist previously and is thus craeted
by this call, this determines whether [notification bot](/help/configure-notification-bot)
will send an announcement about the new stream's creation.
schema:
type: boolean
default: false
example: true
- name: invite_only
in: query
description: |
As described above, this endpoint will create a new stream if passed
a stream name that doesn't already exist. This parameters and the ones
that follow are used to request an initial configuration of a created
stream; they are ignored for streams that already exist.
This parameter determines whether any newly created streams will be
private streams.
schema:
type: boolean
default: false
example: true
- $ref: "#/components/parameters/HistoryPublicToSubscribers"
- $ref: "#/components/parameters/StreamPostPolicy"
- $ref: "#/components/parameters/MessageRetentionDays"
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- allOf:
- $ref: "#/components/schemas/AddSubscriptionsResponse"
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"subscribed": {"iago@zulip.com": ["new stream"]},
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
}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- allOf:
- $ref: "#/components/schemas/AddSubscriptionsResponse"
- example:
{
"already_subscribed":
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"newbie@zulip.com": ["new stream"]},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- allOf:
- $ref: "#/components/schemas/AddSubscriptionsResponse"
- example:
{
"msg": "Unable to access stream (private_stream).",
"result": "error",
}
- allOf:
- $ref: "#/components/schemas/AddSubscriptionsResponse"
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {},
"unauthorized": ["private_stream"],
}
openapi: Remove /users/me/subscriptions from pending_endpoints. In commit 7c71e98, we added a special exception for the /users/me/subscriptions endpoint in the automatic validation test. By adding some extra documentation, we now remove this extra code, as well as the endpoint from the list of pending endpoints.
2019-07-19 07:02:10 +02:00
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_subscriptions
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Update which streams you are are subscribed to.
openapi: Remove /users/me/subscriptions from pending_endpoints. In commit 7c71e98, we added a special exception for the /users/me/subscriptions endpoint in the automatic validation test. By adding some extra documentation, we now remove this extra code, as well as the endpoint from the list of pending endpoints.
2019-07-19 07:02:10 +02:00
parameters:
- name: delete
in: query
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
A list of stream names to unsubscribe from.
openapi: Correctly encode object and array parameters. The current description of object and array parameters in zulip.yaml is wrong and renders incorrect requests on using OpenAPI tools such as SwaggerIO, etc. Fix it by encoding it correctly and changing tests accordingly. Fixes #14380.
2020-06-27 19:23:50 +02:00
content:
application/json:
schema:
type: array
items:
type: string
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
example: ["Verona", "Denmark"]
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
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: Correctly encode object and array parameters. The current description of object and array parameters in zulip.yaml is wrong and renders incorrect requests on using OpenAPI tools such as SwaggerIO, etc. Fix it by encoding it correctly and changing tests accordingly. Fixes #14380.
2020-06-27 19:23:50 +02:00
content:
application/json:
schema:
type: array
items:
type: object
openapi: Use third-party validator for schema validation. Our previous OpenAPI schema validator that we implemented ourselves was useful training wheels for our understanding OpenAPI properly, and was mostly correct. But given that we've finally reached the point where our OpenAPI file accurately describes the API, it makes sense to switch to use an official OpenAPI validator. We lose some ability to do exclude rules for particular elements, but those were primarily important for us when we had a lot of them. As part of this change, we need to add `additionalProperties: false` for all of our dictonaries/objects where we've documented every parameter; otherwise the OpenAPI schema checker won't know that we expect every parameter to be documented.
2020-07-01 19:07:31 +02:00
additionalProperties: false
openapi: Correctly encode object and array parameters. The current description of object and array parameters in zulip.yaml is wrong and renders incorrect requests on using OpenAPI tools such as SwaggerIO, etc. Fix it by encoding it correctly and changing tests accordingly. Fixes #14380.
2020-06-27 19:23:50 +02:00
properties:
name:
type: string
color:
type: string
description:
type: string
example:
[
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"name": "Verona"},
openapi: Correctly encode object and array parameters. The current description of object and array parameters in zulip.yaml is wrong and renders incorrect requests on using OpenAPI tools such as SwaggerIO, etc. Fix it by encoding it correctly and changing tests accordingly. Fixes #14380.
2020-06-27 19:23:50 +02:00
{
"name": "Denmark",
"color": "#e79ab5",
"description": "A Scandinavian country",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
},
openapi: Correctly encode object and array parameters. The current description of object and array parameters in zulip.yaml is wrong and renders incorrect requests on using OpenAPI tools such as SwaggerIO, etc. Fix it by encoding it correctly and changing tests accordingly. Fixes #14380.
2020-06-27 19:23:50 +02:00
]
openapi: Remove /users/me/subscriptions from pending_endpoints. In commit 7c71e98, we added a special exception for the /users/me/subscriptions endpoint in the automatic validation test. By adding some extra documentation, we now remove this extra code, as well as the endpoint from the list of pending endpoints.
2019-07-19 07:02:10 +02:00
required: false
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- required:
- subscribed
- already_subscribed
- removed
- properties:
subscribed:
type: object
openapi: Add response example validation. Add test to validate example responses in zulip.yaml. Also change zulip.yaml for some wrong examples or for cases which were not covered by `test-api`. Also enhance `validate_against_openapi_schema`.
2020-06-10 19:39:24 +02:00
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
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.
additionalProperties:
description: |
`{email_id}`: A list of the names of streams that
the user was subscribed to as a result of the query.
type: array
items:
type: string
already_subscribed:
type: object
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.
additionalProperties:
description: |
`{email_id}`: A list of the names of streams that
the user was already subscribed to.
type: array
items:
type: string
not_removed:
openapi: Add response example validation. Add test to validate example responses in zulip.yaml. Also change zulip.yaml for some wrong examples or for cases which were not covered by `test-api`. Also enhance `validate_against_openapi_schema`.
2020-06-10 19:39:24 +02:00
type: array
items:
type: string
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
A list of the names of streams that the user
is already unsubscribed from, and hence
doesn't need to be unsubscribed.
removed:
openapi: Add response example validation. Add test to validate example responses in zulip.yaml. Also change zulip.yaml for some wrong examples or for cases which were not covered by `test-api`. Also enhance `validate_against_openapi_schema`.
2020-06-10 19:39:24 +02:00
type: array
items:
type: string
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
description: |
A list of the names of streams which were unsubscribed
from as a result of the query.
- example:
{
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
"msg": "",
"subscribed": {},
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"already_subscribed": {"iago@zulip.com": ["Verona"]},
openapi: Specify responses for users/me/subscriptions PATCH operation.
2019-12-05 11:02:20 +01:00
"not_removed": [],
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"removed": ["new stream"],
"result": "success",
}
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: unsubscribe
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Unsubscribe yourself or other users from one or more streams.
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
`DELETE {{ api_url }}/v1/users/me/subscriptions`
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: subscriptions
in: query
description: |
A list of stream names to unsubscribe from. This parameter is called
`streams` in our Python API.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Verona", "Denmark"]
required: true
- $ref: "#/components/parameters/Principals"
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
not_removed:
type: array
items:
type: string
description: |
A list of the names of streams that the user is already unsubscribed
from, and hence doesn't need to be unsubscribed.
removed:
type: array
items:
type: string
description: |
A list of the names of streams which were unsubscribed from as a result
of the query.
- example:
{
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
"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": [],
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"removed": ["new stream"],
"result": "success",
}
"400":
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
description: Bad request.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/NonExistingStreamError"
api: Add GET /users/{user_id}/subscription/{stream_id} endpoint. This new endpoint returns a 'user' dictionary which, as of now, contains a single key 'is_subscribed' with a boolean value that represents whether the user with the given 'user_id' is subscribed to the stream with the given 'stream_id'. Fixes #14966.
2020-05-31 19:10:41 +02:00
/users/{user_id}/subscriptions/{stream_id}:
get:
operationId: get_subscription_status
tags: ["streams"]
description: |
Check whether a user is subscribed to a stream.
`GET {{ api_url }}/v1/users/{user_id}/subscriptions/{stream_id}`
docs: Change next planned major release to 3.0. After some discussion, everyone seems to agree that 3.0 is the more appropriate version number for our next major release. This updates our documentation to reflect that we'll be using 3.0 as our next major release.
2020-06-25 01:25:14 +02:00
**Changes**: New in Zulip 3.0 (feature level 11).
api: Add GET /users/{user_id}/subscription/{stream_id} endpoint. This new endpoint returns a 'user' dictionary which, as of now, contains a single key 'is_subscribed' with a boolean value that represents whether the user with the given 'user_id' is subscribed to the stream with the given 'stream_id'. Fixes #14966.
2020-05-31 19:10:41 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/UserId"
example: 7
- $ref: "#/components/parameters/StreamIdInPath"
example: 1
api: Add GET /users/{user_id}/subscription/{stream_id} endpoint. This new endpoint returns a 'user' dictionary which, as of now, contains a single key 'is_subscribed' with a boolean value that represents whether the user with the given 'user_id' is subscribed to the stream with the given 'stream_id'. Fixes #14966.
2020-05-31 19:10:41 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api: Add GET /users/{user_id}/subscription/{stream_id} endpoint. This new endpoint returns a 'user' dictionary which, as of now, contains a single key 'is_subscribed' with a boolean value that represents whether the user with the given 'user_id' is subscribed to the stream with the given 'stream_id'. Fixes #14966.
2020-05-31 19:10:41 +02:00
description: Success
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
is_subscribed:
type: boolean
description: |
Whether the user is subscribed to the stream.
- example:
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"msg": "", "result": "success", "is_subscribed": false}
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
/users/me/subscriptions/muted_topics:
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: mute_topic
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
This endpoint mutes/unmutes a topic within a stream that the current
user is subscribed to. Muted topics are displayed faded in the Zulip
UI, and are not included in the user's unread count totals.
`PATCH {{ api_url }}/v1/users/me/subscriptions/muted_topics`
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/Stream"
required: false
- $ref: "#/components/parameters/StreamIdInQuery"
required: false
- name: topic
in: query
description: |
The topic to (un)mute. Note that the request will succeed regardless of
whether any messages have been sent to the specified topic.
schema:
type: string
example: dinner
required: true
- name: op
in: query
description: |
Whether to mute (`add`) or unmute (`remove`) the provided topic.
schema:
type: string
enum:
- add
- remove
example: add
required: true
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- allOf:
- $ref: "#/components/schemas/JsonError"
- example:
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"msg": "Topic already muted", "result": "error"}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- allOf:
- $ref: "#/components/schemas/JsonError"
- example:
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"msg": "Topic is not muted", "result": "error"}
openapi: Standardize URL format to use {var_name} syntax. The previous code for the validator test was fairly messy due to checking for both formats of the openapi url, one with <variable_name> and the other with {variable_name}. To eliminate this, we have standardized the format and restricted it to {variable_name} as per the official format at: https://swagger.io/docs/specification/describing-parameters.
2019-07-11 12:45:26 +02:00
/realm/emoji/{emoji_name}:
api docs: Document the custom emoji upload endpoint. Tweaked by tabbott to fix some English phrasing and make the file pointer thing require less Python knowledge. Fixes: #10746.
2018-12-12 19:49:14 +01:00
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: upload_custom_emoji
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
This endpoint is used to upload a custom emoji for use in the user's
organization. Access to this endpoint depends on the
docs: Update URLs to use https://zulip.com. We're migrating to using the cleaner zulip.com domain, which involves changing all of our links from ReadTheDocs and other places to point to the cleaner URL.
2020-06-08 23:04:39 +02:00
[organization's configuration](https://zulip.com/help/only-allow-admins-to-add-emoji).
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/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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: emoji_name
required: true
in: path
description: |
The name that should be associated with the uploaded emoji image/gif.
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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
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
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
openapi: Add regex-to-openapi url pattern matching in the test. With this, the automated validation test will now be able to work with URL patterns containing regular expressions.
2019-07-04 18:12:53 +02:00
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
/realm/emoji:
get:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: get_custom_emoji
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Get all the custom emoji in the user's organization.
`GET {{ api_url }}/v1/realm/emoji`
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
emoji:
openapi_responses: Improve response validation tests. Currently, `validate_against_openapi_schema` checks only the top level of the response dictionary. Improve it so that it can validate objects and arrays at all levels. Also edit zulip.yaml accordingly. And for new response keys which were not defined before add VERY basic documentation.
2020-06-02 18:04:03 +02:00
type: object
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
An object that contains `emoji` objects, each identified with their
emoji ID as the key.
additionalProperties:
type: object
additionalProperties: false
description: |
`{emoji_id}`: Object containing details about the emoji with
the specified ID. It has the following properties:
properties:
id:
type: string
description: |
The ID for this emoji, same as the object's key.
name:
type: string
description: |
The user-friendly name for this emoji. Users in the organization
can use this emoji by writing this name between colons (`:name :`).
source_url:
type: string
description: |
The path relative to the organization's URL where the
emoji's image can be found.
deactivated:
type: boolean
description: |
Whether the emoji has been deactivated or not.
author_id:
type: integer
nullable: true
description: |
The user ID of the user who uploaded the custom emoji.
Will be null if the uploader is unknown.
openapi_responses: Improve response validation tests. Currently, `validate_against_openapi_schema` checks only the top level of the response dictionary. Improve it so that it can validate objects and arrays at all levels. Also edit zulip.yaml accordingly. And for new response keys which were not defined before add VERY basic documentation.
2020-06-02 18:04:03 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
**Changes**: New in Zulip 3.0 (feature level 7). Previously
was accessible via and `author` object with an `id` field.
- example:
{
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
"result": "success",
"msg": "",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"emoji":
{
"1":
{
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/1/emoji/images/1.png",
"deactivated": false,
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"author_id": 5,
},
},
}
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
/users/me/subscriptions/properties:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_subscription_settings
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
This endpoint is used to update the user's personal settings for the
streams they are subscribed to, including muting, color, pinning, and
per-stream notification settings.
`POST {{ api_url }}/v1/users/me/subscriptions/properties`
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: subscription_data
in: query
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`.
content:
application/json:
schema:
type: array
items:
type: object
example:
[
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
{"stream_id": 1, "property": "pin_to_top", "value": true},
{"stream_id": 3, "property": "color", "value": "#f00f00"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
]
required: true
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
subscription_data:
type: array
items:
type: object
additionalProperties: false
properties:
property:
type: string
description: |
The property to be changed. It is one of:
*`color`: The hex value of the user's personal display color for the stream.
*`is_muted`: Whether the stream is [muted](/help/mute-a-stream).
**Changes**: Prior to Zulip 2.1, this feature was
represented by the more confusingly named `in_home_view` (with the
opposite value, `in_home_view=!is_muted`); for
backwards-compatibility, modern Zulip still accepts that value.
*`pin_to_top`: Whether to pin the stream at the top of the stream list.
*`desktop_notifications`: Whether to show desktop notifications for all
messages sent to the stream.
*`audible_notifications`: Whether to play a sound notification for all
messages sent to the stream.
*`push_notifications`: Whether to trigger a mobile push notification for
all messages sent to the stream.
*`email_notifications`: Whether to trigger an email notification for all
messages sent to the stream.
*`in_home_view`: Whether to mute the stream (Legacy property)
*`wildcard_mentions_notify`: whether wildcard mentions trigger notifications
as though they were personal mentions in this stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, wildcard_mentions_notify, for
this stream.
enum:
- color
- push_notifications
- is_muted
- pin_to_top
- desktop_notifications
- audible_notifications
- push_notifications
- email_notifications
- in_home_view
- wildcard_mentions_notify
value:
description: |
The desired value of the property
oneOf:
- type: boolean
- type: string
stream_id:
description: |
The desired value of the property
type: integer
description: |
The same `subscription_data` array sent by the client for the request.
- example:
{
"subscription_data":
[
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"property": "pin_to_top",
"value": true,
"stream_id": 1,
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"property": "color",
"value": "#f00f00",
"stream_id": 3,
},
],
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
"result": "success",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"msg": "",
}
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
/users/{user_id}:
get:
operationId: get_user
tags: ["users"]
description: |
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-users).
*This endpoint is new in Zulip Server 3.0 (feature level 1).*
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/UserId"
- $ref: "#/components/parameters/ClientGravatar"
- $ref: "#/components/parameters/IncludeCustomProfileFields"
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
user:
$ref: "#/components/schemas/User"
- example:
{
"msg": "",
"result": "success",
"user":
{
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"full_name": "King Hamlet",
"is_guest": false,
"profile_data":
{
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"4": {"value": "vim"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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>",
},
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"5": {"value": "1900-1-1"},
"7": {"value": "[11]"},
"6": {"value": "https://blog.zulig.org"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"1":
{
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>",
},
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
"8": {"value": "zulipbot"},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"3":
{
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate",
},
},
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
"is_owner": false,
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com",
},
}
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
patch:
operationId: update_user
tags: ["users"]
description: |
{!api-admin-only.md!}
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).
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/UserId"
- name: full_name
in: query
description: |
The user's full name.
content:
application/json:
schema:
type: string
example: NewName
required: false
- name: role
in: query
description: |
New [role](/help/roles-and-permissions) for the user. Roles are encoded as:
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
* Organization owner: 100
* Organization administrator: 200
* Member: 400
* Guest: 600
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
Only organization owners can add or remove the owner role.
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
The owner role cannot be removed from the only organization owner.
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
**Changes**: New in Zulip 3.0 (feature level 8), replacing the previous
pair of `is_admin` and `is_guest` boolean parameters.
schema:
type: integer
example: 400
required: false
- name: profile_data
in: query
description: |
A dictionary containing the to be updated custom profile field data for the user.
content:
application/json:
schema:
type: array
items:
type: object
example:
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
[{"id": 4, "value": "vim"}, {"id": 5, "value": "1909-04-05"}]
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
required: false
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
$ref: "#/components/responses/SimpleSuccess"
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"400":
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
- example:
{
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
"result": "error",
"msg": "Guests cannot be organization administrators",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"code": "BAD_REQUEST",
}
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
delete:
operationId: deactivate_user
tags: ["users"]
description: |
{!api-admin-only.md!}
[Deactivates a
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
given their user ID.
`DELETE {{ api_url }}/v1/users/{user_id}`
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/UserId"
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
description: Success
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"msg": "", "result": "success"}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"400":
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
description: Bad Request
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
- example:
{
openapi: Move `/users/{user_id}` below endpoints with similar regex. openapi-core, the request validator has a bug due to which data type of path parameters is not checked. Hence `/users/{user_id}` can match with `users/me`. So change the position of`/user/{user_id}` after all such possible matches to avoid errors. See https://github.com/p1c2u/openapi-core/issues/226 for details.
2020-07-09 18:56:52 +02:00
"msg": "Cannot deactivate the only organization administrator",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
/realm/filters:
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
get:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: get_linkifiers
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
List all of an organization's configured
[linkifiers](/help/add-a-custom-linkification-filter), regular
expression patterns that are automatically linkified when they appear
in messages and topics.
`GET {{ api_url }}/v1/realm/filters`
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
filters:
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
type: array
items:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
type: array
items:
oneOf:
- type: string
- type: integer
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-linkifier) article for
details on what each field means.
- example:
{
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
"msg": "",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"filters":
[
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
[
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"#(?P<id>[0-9]+)",
"https://github.com/zulip/zulip/issues/%(id)s",
1,
],
],
"result": "success",
}
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
post:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: add_linkifier
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Configure [linkifiers](/help/add-a-custom-linkification-filter),
regular expression patterns that are automatically linkified when they
appear in messages and topics.
`POST {{ api_url }}/v1/realm/filters`
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: pattern
in: query
description: |
The [Python regular
expression](https://docs.python.org/3/howto/regex.html) that should
trigger the linkifier.
schema:
type: string
example: "#(?P<id>[0-9]+)"
required: true
- name: url_format_string
in: query
description: |
The URL used for the link. If you used named groups for the `pattern`,
you can insert their content here with
`%(name_of_the_capturing_group)s`.
schema:
type: string
example: https://github.com/zulip/zulip/issues/%(id)s
required: true
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
id:
type: integer
description: |
The numeric ID assigned to this filter.
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"id": 42, "result": "success", "msg": ""}
openapi: Standardize URL format to use {var_name} syntax. The previous code for the validator test was fairly messy due to checking for both formats of the openapi url, one with <variable_name> and the other with {variable_name}. To eliminate this, we have standardized the format and restricted it to {variable_name} as per the official format at: https://swagger.io/docs/specification/describing-parameters.
2019-07-11 12:45:26 +02:00
/realm/filters/{filter_id}:
api docs: Document DELETE /realm/filters/<filter_id>.
2018-08-14 03:20:39 +02:00
delete:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: remove_linkifier
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Remove [linkifiers](/help/add-a-custom-linkification-filter), regular
expression patterns that are automatically linkified when they appear
in messages and topics.
`DELETE {{ api_url }}/v1/realm/filters/{filter_id}`
api docs: Document DELETE /realm/filters/<filter_id>.
2018-08-14 03:20:39 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: filter_id
in: path
description: |
The ID of the filter that you want to remove.
schema:
type: integer
example: 42
required: true
api docs: Document DELETE /realm/filters/<filter_id>.
2018-08-14 03:20:39 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document DELETE /realm/filters/<filter_id>.
2018-08-14 03:20:39 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
/register:
post:
openapi: Use correct `operationId` atrribute for endpoints. Update `operationId` of some endpoints to their correct version.
2020-05-22 05:39:08 +02:00
operationId: register_queue
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
This powerful endpoint can be used to register a Zulip "event queue"
(subscribed to certain types of "events", or updates to the messages and
other Zulip data the current user has access to), as well as to fetch
the current state of that data.
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: apply_markdown
in: query
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)
schema:
type: boolean
default: false
example: true
- $ref: "#/components/parameters/ClientGravatar"
- name: slim_presence
in: query
description: |
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
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
**Changes**: New in Zulip 3.0 (Unstable with no feature level yet).
schema:
type: boolean
default: false
example: true
- $ref: "#/components/parameters/Event_types"
- name: all_public_streams
in: query
description: |
Set to `True` if you would like to receive events that occur within all
public streams.
schema:
type: boolean
default: false
example: true
- $ref: "#/components/parameters/IncludeSubscribers"
- name: client_capabilities
in: query
description: |
Dictionary containing details on features the client supports that are
relevant to the format of responses sent by the server.
* `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.
* `bulk_message_deletion`: Boolean for whether the client's
handler for the `delete_message` event type has been
updated to process the new bulk format (with a
`message_ids`, rather than a singleton `message_id`).
Otherwise, the server will send `delete_message` events
in a loop. New in Zulip 3.0 (feature level 13). This
capability is for backwards-compatibility; it will be
required in a future server release.
* `user_avatar_url_field_optional`: Boolean for whether the
client required avatar URLs for all users, or supports
using `GET /avatar/{user_id}` to access user avatars. If the
client has this capability, the server may skip sending a
`avatar_url` field in the `realm_user` at its sole discretion
to optimize network performance. This is an important optimization
in organizations with 10,000s of users.
New in Zulip 3.0 (feature level 18).
content:
application/json:
schema:
type: object
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
example: {"notification_settings_null": true}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: fetch_event_types
in: query
description: |
Same as the `event_types` parameter except that the values in
`fetch_event_types` are used to fetch initial data. If
`fetch_event_types` is not provided, `event_types` is used and if
`event_types` is not provided, this parameter defaults to `None`.
content:
application/json:
schema:
type: array
items:
type: string
example: ["message"]
- $ref: "#/components/parameters/Narrow"
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
queue_id:
type: string
description: |
The ID of the queue that has been allocated for your client.
last_event_id:
type: integer
description: |
The initial value of `last_event_id` to pass to `GET /api/v1/events`.
zulip_feature_level:
type: integer
description: |
The server's current [Zulip feature level](/api/changelog).
zulip_version:
type: string
description: |
The server's version.
- example:
{
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
"last_event_id": -1,
"msg": "",
"queue_id": "1517975029:0",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"realm_emoji":
{
"1":
{
api: Simplify format of realm_emoji author data. There's no reason to send data beyond the user `id` of the uploader, and reason not to, as the previous model was both awkward when `author=None` and resulted in unecessary parsing complexity for clients. Modified by tabbott to add the frontend changes and API documentation. Fixes #15115.
2020-05-29 11:11:48 +02:00
"author_id": 5,
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
"deactivated": false,
"id": "1",
"name": "green_tick",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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,
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"zulip_version": "2.1.0",
}
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
/server_settings:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_server_settings
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["server_and_organizations"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Fetch global settings for a Zulip server.
`GET {{ api_url }}/v1/server_settings`
**Note:** this endpoint does not require any authentication at all, and you can use it to check:
* If this is a Zulip server, and if so, what version of Zulip it's running.
* What a Zulip client (e.g. a mobile app or
[zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to
know in order to display a login prompt for the server (e.g. what
authentication methods are available).
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
authentication_methods:
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
type: object
openapi: Use third-party validator for schema validation. Our previous OpenAPI schema validator that we implemented ourselves was useful training wheels for our understanding OpenAPI properly, and was mostly correct. But given that we've finally reached the point where our OpenAPI file accurately describes the API, it makes sense to switch to use an official OpenAPI validator. We lose some ability to do exclude rules for particular elements, but those were primarily important for us when we had a lot of them. As part of this change, we need to add `additionalProperties: false` for all of our dictonaries/objects where we've documented every parameter; otherwise the OpenAPI schema checker won't know that we expect every parameter to be documented.
2020-07-01 19:07:31 +02:00
additionalProperties: false
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
deprecated: true
description: |
Each key-value pair in the object indicates whether the authentication
method is enabled on this server.
**Changes**: Deprecated in Zulip 2.1, in favor of the more expressive
`external_authentication_methods`.
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
properties:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
password:
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
Whether the user can authenticate using password.
type: boolean
dev:
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
Whether the user can authenticate using development api key.
type: boolean
email:
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
Whether the user can authenticate using email.
type: boolean
ldap:
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
Whether the user can authenticate using ldap.
type: boolean
remoteuser:
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
Whether the user can authenticate using remoteuser.
type: boolean
github:
description: |
Whether the user can authenticate using their github account.
type: boolean
azuread:
description: |
Whether the user can authenticate using their azuread account.
type: boolean
gitlab:
description: |
Whether the user can authenticate using their gitlab account.
type: boolean
apple:
description: |
Whether the user can authenticate using their apple account.
type: boolean
google:
description: |
Whether the user can authenticate using their google account.
type: boolean
saml:
description: |
Whether the user can authenticate using saml.
type: boolean
external_authentication_methods:
type: array
description: |
A list of dictionaries describing the available external
authentication methods (E.g. Google, GitHub, or SAML)
enabled for this organization.
The list is sorted in the order in which these
authentication methods should be displayed.
**Changes**: New in Zulip 2.1.
items:
type: object
additionalProperties: false
properties:
name:
type: string
description: |
A unique, table, machine-readable name for the authentication method,
intended to be used by clients with special behavior for specific
authenatication methods to correctly identify the method.
display_name:
type: string
description: |
Display name of the authentication method, to be used in all buttons
for the authentication method.
display_icon:
type: string
nullable: true
description: |
URL for an image to be displayed as an icon in all buttons for
the external authentication method.
When null, no icon should be displayed.
login_url:
type: string
description: |
URL to be used to initiate authentication using this method.
signup_url:
type: string
description: |
URL to be used to initiate account registration using this method.
zulip_version:
type: string
description: |
The version of Zulip running in the server.
zulip_feature_level:
type: integer
description: |
An integer indicating what features are
available on the server. The feature level increases monotonically;
a value of N means the server supports all API features introduced
before feature level N. This is designed to provide a simple way
for client apps to decide whether the server supports a given
feature or API change. See the [changelog](/api/changelog) for
details on what each feature level means.
**Changes**. New in Zulip 3.0. We recommend using an implied value
of 0 for Zulip servers that do not send this field.
push_notifications_enabled:
type: boolean
description: |
Whether mobile/push notifications are enabled.
is_incompatible:
type: boolean
description: |
Whether the Zulip client that has sent a request to this endpoint is
deemed incompatible with the server.
email_auth_enabled:
type: boolean
description: |
Setting for allowing users authenticate with an email-password
combination.
require_email_format_usernames:
type: boolean
description: |
Whether all valid usernames for authentication to this
organization will be email addresses. This is important
for clients to know whether to do client side validation
of email address format in a login prompt.
This value will be false if the server has [LDAP
authentication][ldap-auth] enabled with a username and
password combination.
realm_uri:
type: string
description: |
The organization's canonical URL.
realm_name:
type: string
description: |
The organization's name (for display purposes).
realm_icon:
type: string
description: |
The URL for the organization's logo formatted as a square image,
used for identifying the organization in small locations in the
mobile and desktop apps.
realm_description:
type: string
description: |
HTML description of the organization, as configured by the [organization
profile](/help/create-your-organization-profile).
- example:
{
"authentication_methods":
{
"password": true,
"dev": true,
"email": true,
"ldap": false,
"remoteuser": false,
"github": true,
"azuread": false,
"google": true,
"saml": 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
"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",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"external_authentication_methods":
[
{
"name": "saml:idp_name",
"display_name": "SAML",
"display_icon": null,
"login_url": "/accounts/login/social/saml/idp_name",
"signup_url": "/accounts/register/social/saml/idp_name",
},
{
"name": "google",
"display_name": "Google",
"display_icon": "/static/images/landing-page/logos/googl_e-icon.png",
"login_url": "/accounts/login/social/google",
"signup_url": "/accounts/register/social/google",
},
{
"name": "github",
"display_name": "GitHub",
"display_icon": "/static/images/landing-page/logos/github-icon.png",
"login_url": "/accounts/login/social/github",
"signup_url": "/accounts/register/social/github",
},
],
}
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
/settings/notifications:
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_notification_settings
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
This endpoint is used to edit the user's global notification settings.
openapi: Make api-docs filename match with operationIds. api docs filenames are basically the operationId of their endpoint in zulip.yaml with `_` replaced by `-`. But some operationIds have changed, so change the affected filenames. Make changes in other files accordingly.
2020-06-11 14:44:00 +02:00
See [this endpoint](/api/update-subscription-settings) for
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
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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: enable_stream_desktop_notifications
in: query
description: |
Enable visual desktop notifications for stream messages.
schema:
type: boolean
example: true
- name: enable_stream_email_notifications
in: query
description: |
Enable email notifications for stream messages.
schema:
type: boolean
example: true
- name: enable_stream_push_notifications
in: query
description: |
Enable mobile notifications for stream messages.
schema:
type: boolean
example: true
- name: enable_stream_audible_notifications
in: query
description: |
Enable audible desktop notifications for stream messages.
schema:
type: boolean
example: true
- name: notification_sound
in: query
description: |
Notification sound name.
content:
application/json:
schema:
type: string
example: ding
- name: enable_desktop_notifications
in: query
description: |
Enable visual desktop notifications for private messages and @-mentions.
schema:
type: boolean
example: true
- name: enable_sounds
in: query
description: |
Enable audible desktop notifications for private messages and
@-mentions.
schema:
type: boolean
example: true
- name: enable_offline_email_notifications
in: query
description: |
Enable email notifications for private messages and @-mentions received
when the user is offline.
schema:
type: boolean
example: true
- name: enable_offline_push_notifications
in: query
description: |
Enable mobile notification for private messages and @-mentions received
when the user is offline.
schema:
type: boolean
example: true
- name: enable_online_push_notifications
in: query
description: |
Enable mobile notification for private messages and @-mentions received
when the user is online.
schema:
type: boolean
example: true
- name: enable_digest_emails
in: query
description: |
Enable digest emails when the user is away.
schema:
type: boolean
example: true
- name: enable_login_emails
in: query
description: |
Enable email notifications for new logins to account.
schema:
type: boolean
example: true
- name: message_content_in_email_notifications
in: query
description: |
Include the message's content in missed messages email notifications.
schema:
type: boolean
example: true
- name: pm_content_in_desktop_notifications
in: query
description: |
Include content of private messages in desktop notifications.
schema:
type: boolean
example: true
- name: wildcard_mentions_notify
in: query
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
schema:
type: boolean
example: true
- name: desktop_icon_count_display
in: query
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
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
* 1 - All unreads
* 2 - Private messages and mentions
* 3 - None
content:
application/json:
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: realm_name_in_notifications
in: query
description: |
Include organization name in subject of missed message emails.
schema:
type: boolean
example: true
- name: presence_enabled
in: query
description: |
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
Display the presence status to other users when online.
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
schema:
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
type: boolean
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
example: true
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
enable_desktop_notifications:
type: boolean
description: |
The setting for `enable_desktop_notifications`, if it was changed in
this request.
enable_digest_emails:
type: boolean
description: |
The setting for `enable_digest_emails`, if it was changed in this
request.
enable_offline_email_notifications:
type: boolean
description: |
The setting for `enable_offline_email_notifications`, if it was changed
in this request.
enable_offline_push_notifications:
type: boolean
description: |
The setting for `enable_offline_push_notifications`, if it was changed
in this request.
enable_online_push_notifications:
type: boolean
description: |
The setting for `enable_online_push_notifications`, if it was changed in
this request.
enable_sounds:
type: boolean
description: |
The setting for `enable_sounds`, if it was changed in this request.
enable_stream_email_notifications:
type: boolean
description: |
The setting for `enable_stream_email_notifications`, if it was changed
in this request.
enable_stream_push_notifications:
type: boolean
description: |
The setting for `enable_stream_push_notifications`, if it was changed in
this request.
enable_stream_audible_notifications:
type: boolean
description: |
The setting for `enable_stream_audible_notifications`, if it was changed
in this request.
message_content_in_email_notifications:
type: boolean
description: |
The setting for `message_content_in_email_notifications`, if it was
changed in this request.
- example:
{
api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing.
2018-08-10 02:15:45 +02:00
"enable_offline_push_notifications": true,
"enable_online_push_notifications": true,
"msg": "",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "success",
}
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
/streams:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_streams
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Get all streams that the user has access to.
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
`GET {{ api_url }}/v1/streams`
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: include_public
in: query
description: |
Include all public streams.
schema:
type: boolean
default: true
example: false
- name: include_subscribed
in: query
description: |
Include all streams that the user is subscribed to.
schema:
type: boolean
default: true
example: false
- name: include_all_active
in: query
description: |
Include all active streams. The user must have administrative privileges
to use this parameter.
schema:
type: boolean
default: false
example: true
- name: include_default
in: query
description: |
Include all default streams for the user's realm.
schema:
type: boolean
default: false
example: true
- name: include_owner_subscribed
in: query
description: |
If the user is a bot, include all streams that the bot's owner is
subscribed to.
schema:
type: boolean
default: false
example: true
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
streams:
description: |
A list of `stream` objects with details on the requested streams.
type: array
items:
openapi: Move `stream` schema to components section. The stream schema is used in two locations so move it to the components section. Also the `is_default` key returned by `/streams` is not returned by `/events`. So handle it separately.
2020-07-21 13:44:06 +02:00
allOf:
- $ref: "#/components/schemas/BasicStream"
- properties:
is_default:
type: boolean
description: |
Whether the given stream is a
[default stream](/help/set-default-streams-for-new-users). Only
returned if the `include_default` parameter is `true`.
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- example:
{
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
"msg": "",
"result": "success",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"streams":
[
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"description": "A Scandinavian country",
"invite_only": false,
"name": "Denmark",
"stream_id": 1,
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"description": "Yet another Italian city",
"invite_only": false,
"name": "Rome",
"stream_id": 2,
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"description": "Located in the United Kingdom",
"invite_only": false,
"name": "Scotland",
"stream_id": 3,
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"description": "A northeastern Italian city",
"invite_only": false,
"name": "Venice",
"stream_id": 4,
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"description": "A city in Italy",
"invite_only": false,
"name": "Verona",
"stream_id": 5,
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"description": "New stream for testing",
"invite_only": false,
"name": "new stream",
"stream_id": 6,
},
],
}
"400":
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
- example:
{
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
/streams/{stream_id}:
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: delete_stream
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
[Delete the stream](/help/delete-a-stream) with the ID `stream_id`.
`DELETE {{ api_url }}/v1/streams/{stream_id}`
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/StreamIdInPath"
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"msg": "", "result": "success"}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"400":
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
- properties:
msg:
type: string
- example:
{
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api_docs: Add documentation for update_stream.
2019-06-23 14:38:28 +02:00
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_stream
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["streams"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Configure the stream with the ID `stream_id`. This endpoint supports
an organization administrator editing any property of a stream,
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
including:
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
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
* 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}`
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
- name: description
in: query
description: |
The new description for the stream.
content:
application/json:
schema:
type: string
example: This stream is related to football dicsussions.
required: false
- name: new_name
in: query
description: |
The new name for the stream.
content:
application/json:
schema:
type: string
example: Italy
required: false
- name: is_private
in: query
description: |
Change whether the stream is a private stream.
schema:
type: boolean
example: true
required: false
- name: is_announcement_only
in: query
deprecated: true
description: |
Whether the stream is limited to announcements.
**Changes**: Deprecated in Zulip 3.0 (feature level 1), use
`stream_post_policy` instead.
schema:
type: boolean
example: true
required: false
- $ref: "#/components/parameters/StreamPostPolicy"
- $ref: "#/components/parameters/HistoryPublicToSubscribers"
- $ref: "#/components/parameters/MessageRetentionDays"
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
description: Success.
content:
application/json:
schema:
api_docs: Add documentation for delete_stream.
2019-06-22 08:22:32 +02:00
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"msg": "", "result": "success"}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"400":
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
description: Bad request.
content:
application/json:
schema:
api_docs: Add documentation for delete_stream.
2019-06-22 08:22:32 +02:00
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
- example:
{
tools/test-api: Test Client.delete_stream.
2019-04-08 10:11:18 +02:00
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
/typing:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: set_typing_status
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Send an event indicating that the user has started or stopped typing
on their client. See
[the typing notification docs](https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html)
for details on Zulip's typing notifications protocol.
`POST {{ api_url }}/v1/typing`
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: op
in: query
description: |
Whether the user has started (`start`) or stopped (`stop`) to type.
schema:
type: string
enum:
- start
- stop
example: start
required: true
- name: to
in: query
description: |
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.).
**Changes**: Before Zulip 2.0, this parameter accepted only a JSON-encoded
list of email addresses. Support for the email address-based format was
removed in Zulip 3.0 (feature level 11).
content:
application/json:
schema:
type: array
items:
type: integer
example: [9, 10]
required: true
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
description: Success.
content:
application/json:
schema:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/JsonSuccess"
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
/user_groups/create:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: create_user_group
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Create a new [user group](/help/user-groups).
`POST {{ api_url }}/v1/user_groups/create`
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- name: name
in: query
description: |
The name of the user group.
schema:
type: string
example: marketing
required: true
- name: description
in: query
description: |
The description of the user group.
schema:
type: string
example: The marketing team.
required: true
- name: members
in: query
description: |
An array containing the user IDs of the initial members for the
new user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [1, 2, 3, 4]
required: true
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"msg": "", "result": "success"}
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"400":
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
- example:
{
"result": "error",
"code": "BAD_REQUEST",
"msg": "Invalid user ID: 500",
}
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
/user_groups/{group_id}:
patch:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: update_user_group
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Update the name or description of a [user group](/help/user-groups).
`PATCH {{ api_url }}/v1/user_groups/{group_id}`
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/GroupId"
- name: name
in: query
description: |
The new name of the group.
schema:
type: string
example: marketing team
required: true
- name: description
in: query
description: |
The new description of the group.
schema:
type: string
example: The marketing team.
required: true
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
$ref: "#/components/responses/SimpleSuccess"
api_docs: Add documentation for create_user_group.
2019-06-24 22:27:06 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"400":
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
- example:
{
api_docs: Add documentation for update_user_group.
2019-06-25 21:43:53 +02:00
"code": "BAD_REQUEST",
"msg": "Invalid user group",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
delete:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: remove_user_group
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Delete a [user group](/help/user-groups).
`DELETE {{ api_url }}/v1/user_groups/{group_id}`
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/GroupId"
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"result": "success", "msg": ""}
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"400":
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
description: Bad request.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
- example:
{
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
"code": "BAD_REQUEST",
"msg": "Invalid user group",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api_docs: Add documentation for remove_user_group.
2019-06-25 22:00:34 +02:00
api: Add GET /user_groups documentation. This documents our GET endpoint for interacting with Zulip's user groups feature. Fixes #10298.
2018-08-18 23:06:53 +02:00
/user_groups:
get:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: get_user_groups
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["users"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
openapi: Use description markdown for rendering endpoint descriptions. Firstly, change endpoint descriptions in zulip.yaml so that they match their counterpart in the api docs. Then edit the api docs so that they use api description markdown extension for displaying endpoint description.
2020-04-28 20:00:46 +02:00
Fetches all of the user groups in the organization.
`GET {{ api_url }}/v1/user_groups`
api: Add GET /user_groups documentation. This documents our GET endpoint for interacting with Zulip's user groups feature. Fixes #10298.
2018-08-18 23:06:53 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
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
description: Success.
content:
application/json:
schema:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
user_groups:
type: array
items:
type: object
additionalProperties: false
properties:
description:
type: string
description: |
The human-readable description of the user group.
id:
openapi_responses: Fix get_user_groups.
2020-05-27 14:11:41 +02:00
type: integer
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
description: |
The user group's integer id.
members:
type: array
description: |
The integer User IDs of the user group members.
items:
type: integer
name:
type: string
description: |
User group name.
description: |
A list of `user_group` objects, which contain a `description`, a `name`,
their `id` and the list of members of the user group.
- example:
{
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
"msg": "",
"result": "success",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"description": "Characters of Hamlet",
"id": 1,
"name": "hamletcharacters",
"members": [3, 4],
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
},
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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
openapi_docs: Replace `argument` with `parameter`. The term `parameter` is a better word than `argument` for data passed to an API endpoint; this is why OpenAPI uses in their terminology. Replace `argument` with `parameter` in the API docs to improve their readability. Fixes #15435.
2020-06-18 15:35:25 +02:00
# documenting the parameters for call_on_each_event and friends.
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
post:
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
(Ignored)
api docs: Migrate REAL-TIME /events to OpenAPI. Migrate "call_on_each_event" from api/arguments.json to /events:real-time in OpenAPI. This is a bit of a hack, but it lets us eliminate this secondary arguments.json file, which is probably worth it. Tweaked by tabbott to fix various formatting issues in the original documentation while I was looking at it.
2020-03-18 02:40:44 +01:00
parameters:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/parameters/Narrow"
- $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
security:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- 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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
# Makeshift response for this hack entry.
"200":
description: Success
api_docs: Migrate POST /rest-error-handling. This commit migrates payload of errors which are common to many endpoints to /rest-error-handling:post in OpenAPI.
2020-04-02 02:15:28 +02:00
/rest-error-handling:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: rest_error_handling
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["real_time_events"]
api_docs: Migrate POST /rest-error-handling. This commit migrates payload of errors which are common to many endpoints to /rest-error-handling:post in OpenAPI.
2020-04-02 02:15:28 +02:00
description: |
Common error to many endpoints
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- allOf:
- $ref: "#/components/schemas/InvalidApiKeyError"
- allOf:
- $ref: "#/components/schemas/MissingArgumentError"
- allOf:
- $ref: "#/components/schemas/UserNotAuthorizedError"
api_docs: Migrate POST /zulip-outgoing-webhook. This commit migrates zulip outging webhook payload to /zulip-outgoing-webhook:post in OpenAPI. Since this migrates the last payloads from api/fixtures.json to OpenAPI, this commit removes api/fixtures.json file and the functions accessing the file. Tweaked by tabbott to further remove an unnecessary conditional.
2020-04-02 03:42:59 +02:00
/zulip-outgoing-webhook:
post:
openapi: Add 'operationId' attribute to endpoints. 'operationId' helps code generators in naming functions and other purposes. So name operationId of endpoints as their function names in python-zulip-api if it exists else use most appropriate function name. Part of #14100 .
2020-05-08 14:36:10 +02:00
operationId: zulip_outgoing_webhooks
openapi: Add 'tags' attribute to endpoints. 'tags' attribute is helpful in differentiating and grouping the endpoints on basis of their usage. For example tags like 'messages' help in grouping all endpoints related to messages and thus make the api specification more user-friendly. So give tags to the endpoints on the basis of what heading they are under in the API docs.
2020-05-12 16:45:35 +02:00
tags: ["webhooks"]
api_docs: Migrate POST /zulip-outgoing-webhook. This commit migrates zulip outging webhook payload to /zulip-outgoing-webhook:post in OpenAPI. Since this migrates the last payloads from api/fixtures.json to OpenAPI, this commit removes api/fixtures.json file and the functions accessing the file. Tweaked by tabbott to further remove an unnecessary conditional.
2020-04-02 03:42:59 +02:00
description: |
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
Outgoing Webhooks allows to build or set up Zulip integrations which are
notified when certain types of messages are sent in Zulip.
api_docs: Migrate POST /zulip-outgoing-webhook. This commit migrates zulip outging webhook payload to /zulip-outgoing-webhook:post in OpenAPI. Since this migrates the last payloads from api/fixtures.json to OpenAPI, this commit removes api/fixtures.json file and the functions accessing the file. Tweaked by tabbott to further remove an unnecessary conditional.
2020-04-02 03:42:59 +02:00
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
api_docs: Migrate POST /zulip-outgoing-webhook. This commit migrates zulip outging webhook payload to /zulip-outgoing-webhook:post in OpenAPI. Since this migrates the last payloads from api/fixtures.json to OpenAPI, this commit removes api/fixtures.json file and the functions accessing the file. Tweaked by tabbott to further remove an unnecessary conditional.
2020-04-02 03:42:59 +02:00
description: |
Success
content:
application/json:
schema:
openapi: Use third-party validator for schema validation. Our previous OpenAPI schema validator that we implemented ourselves was useful training wheels for our understanding OpenAPI properly, and was mostly correct. But given that we've finally reached the point where our OpenAPI file accurately describes the API, it makes sense to switch to use an official OpenAPI validator. We lose some ability to do exclude rules for particular elements, but those were primarily important for us when we had a lot of them. As part of this change, we need to add `additionalProperties: false` for all of our dictonaries/objects where we've documented every parameter; otherwise the OpenAPI schema checker won't know that we expect every parameter to be documented.
2020-07-01 19:07:31 +02:00
additionalProperties: false
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
properties:
data:
type: string
description: |
The message content, in raw markdown format (not rendered to HTML).
trigger:
type: string
description: |
What aspect of the message triggered the outgoing webhook notification.
Possible values include `private_message` and `mention`.
token:
type: string
description: |
A string of alphanumeric characters that can be use to authenticate the
webhook request. You can get the token used by a given outgoing webhook bot
in the `zuliprc` file downloaded when creating the bot.
message:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- description: |
A dict containing details on the message that triggered the
outgoing webhook, in the format used by [`GET /messages`](/api/get-messages).
- $ref: "#/components/schemas/Messages"
openapi: Edit `Messages` component to match the `message` event object. The `Messages` schema present in `#/components/schemas` was a combination of all keys possible in any message object used in Zulip. Edit it so that the original `Messages` contains just the keys present in the `message` event. Also make another schema `GetMessages` which adds a few other keys which are received when using `GET /messages`. The message object in the `/zulip-outgoing-webhook` has also been modified and corrected.
2020-07-20 17:28:20 +02:00
- properties:
rendered_content:
type: string
description: |
The content/body of the message rendered in HTML.
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
bot_email:
type: string
description: |
Email of the bot user.
example:
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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",
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
},
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"bot_email": "outgoing-bot@localhost",
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
}
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
calls: Add Big Blue Button as a Video Call Provider. Big Blue Button needs an API secret so communication to creating a room has to be done server side. Fixes #14763.
2020-04-27 22:41:31 +02:00
/calls/bigbluebutton/create:
get:
tags: ["streams"]
operationId: create_big_blue_button_video_call
description: |
Create a video call url for a Big Blue Button video call.
Requires Big Blue Button to be configured on the Zulip server.
responses:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"200":
calls: Add Big Blue Button as a Video Call Provider. Big Blue Button needs an API secret so communication to creating a room has to be done server side. Fixes #14763.
2020-04-27 22:41:31 +02:00
description: Success.
content:
application/json:
schema:
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
url:
description: |
The url for the Big Blue Button video call.
type: string
example: "/calls/bbb/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22"
- example:
{
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
"msg": "",
"result": "success",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"url": "/calls/bbb/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22",
}
calls: Add Big Blue Button as a Video Call Provider. Big Blue Button needs an API secret so communication to creating a room has to be done server side. Fixes #14763.
2020-04-27 22:41:31 +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
components:
#######################
# Security definitions
#######################
securitySchemes:
BasicAuth:
type: http
scheme: basic
openapi: Use "description: |" for multiline paragraphs. "description: |" supports markdown and is overall better for writing multiline paragraphs. So use it in multiline paragraphs and line-wrap the newly formed paragraphs accordingly. Edited by tabbott to change most single-line descriptions to use this format as well.
2020-04-16 13:20:32 +02:00
description: |
Basic authentication, with the user's email as the username, and the API
key as the password. The API key can be fetched using the
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
schemas:
openapi: Move `stream` schema to components section. The stream schema is used in two locations so move it to the components section. Also the `is_default` key returned by `/streams` is not returned by `/events`. So handle it separately.
2020-07-21 13:44:06 +02:00
BasicStream:
type: object
additionalProperties: false
properties:
stream_id:
type: integer
description: |
The unique ID of the stream.
name:
type: string
description: |
The name of the stream.
description:
type: string
description: |
The short description of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
stream/docs: Add date_created to Stream.API_FIELDS. The parameter Stream.date_created is now sent down to the clients for both: - client.get_streams() - client.list_subscriptions() API docs updated for stream and subscriptions. Fixes #15410
2020-07-25 05:44:12 +02:00
date_created:
type: integer
description: |
The UNIX timestamp for when the stream was created, in UTC seconds.
api: Document API change for Stream.date_created.
2020-07-28 02:10:59 +02:00
**Changes**: New in Zulip 4.0 (feature level 30).
openapi: Move `stream` schema to components section. The stream schema is used in two locations so move it to the components section. Also the `is_default` key returned by `/streams` is not returned by `/events`. So handle it separately.
2020-07-21 13:44:06 +02:00
invite_only:
type: boolean
description: |
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
rendered_description:
type: string
description: |
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
is_web_public:
type: boolean
description: |
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
stream_post_policy:
type: integer
description: |
Policy for which users can post messages to the stream.
* 1 => Any user can post.
* 2 => Only administrators can post.
* 3 => Only new members can post.
**Changes**: New in Zulip 3.0, replacing the previous
`is_announcement_only` boolean.
message_retention_days:
type: integer
nullable: true
description: |
Number of days that messages sent to this stream will be stored
before being automatically deleted by the [message retention
policy](/help/message-retention-policy). There are two special values:
* `null`, the default, means the stream will inherit the organization
level setting.
* `-1` encodes retaining messages in this stream forever.
**Changes**: New in Zulip 3.0 (feature level 17).
history_public_to_subscribers:
type: boolean
description: |
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
first_message_id:
type: integer
nullable: true
description: |
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Null is used for streams with no message history.
is_announcement_only:
type: boolean
deprecated: true
description: |
Whether the given stream is announcement only or not.
**Changes**: Deprecated in Zulip 3.0 (feature level 1), use
`stream_post_policy` instead.
openapi: Move `subscriptions` schema to the components section. The `subscriptions` has use in multiple endpoints and hence instead of redefining it at every point move it to the the components section for easier reuse.
2020-07-20 13:25:52 +02:00
Subscriptions:
type: object
additionalProperties: false
properties:
stream_id:
type: integer
description: |
The unique ID of a stream.
name:
type: string
description: |
The name of a stream.
description:
type: string
description: |
The short description of a stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
rendered_description:
type: string
description: |
A short description of a stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
stream/docs: Add date_created to Stream.API_FIELDS. The parameter Stream.date_created is now sent down to the clients for both: - client.get_streams() - client.list_subscriptions() API docs updated for stream and subscriptions. Fixes #15410
2020-07-25 05:44:12 +02:00
date_created:
type: integer
description: |
The UNIX timestamp for when the stream was created, in UTC seconds.
api: Document API change for Stream.date_created.
2020-07-28 02:10:59 +02:00
**Changes**: New in Zulip 4.0 (feature level 30).
openapi: Move `subscriptions` schema to the components section. The `subscriptions` has use in multiple endpoints and hence instead of redefining it at every point move it to the the components section for easier reuse.
2020-07-20 13:25:52 +02:00
invite_only:
type: boolean
description: |
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
# TODO: This subscribers item should probably be declared optional more
# explicitly in the OpenAPI format?
subscribers:
type: array
items:
type: integer
description: |
A list of user IDs of users who are also subscribed
to a given stream. Included only if `include_subscribers` is `true`.
desktop_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether desktop notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_desktop_notifications, for
this stream.
email_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether email notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_email_notifications, for
this stream.
wildcard_mentions_notify:
type: boolean
nullable: true
description: |
A boolean specifying whether wildcard mentions
trigger notifications as though they were personal
mentions in this stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, wildcard_mentions_notify, for
this stream.
push_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether push notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_push_notifications, for
this stream.
audible_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether audible notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_audible_notifications, for
this stream.
pin_to_top:
type: boolean
description: |
A boolean specifying whether the given stream has been pinned
to the top.
email_address:
type: string
description: |
Email address of the given stream, used for
[sending emails to the stream](/help/message-a-stream-by-email).
is_muted:
type: boolean
description: |
Whether the user has muted the stream. Muted streams do
not count towards your total unread count and do not show up in
`All messages` view (previously known as `Home` view).
**Changes**: Prior to Zulip 2.1, this feature was
represented by the more confusingly named `in_home_view` (with the
opposite value, `in_home_view=!is_muted`).
in_home_view:
type: boolean
deprecated: true
description: |
Legacy property for if the given stream is muted, with inverted meeting.
**Deprecated**; clients should use is_muted where available.
is_announcement_only:
type: boolean
deprecated: true
description: |
Whether only organization administrators can post to the stream.
**Changes**: Deprecated in Zulip 3.0 (feature level 1), use
`stream_post_policy` instead.
is_web_public:
type: boolean
description: |
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
color:
type: string
description: |
The user's personal color for the stream.
stream_post_policy:
type: integer
description: |
Policy for which users can post messages to the stream.
* 1 => Any user can post.
* 2 => Only administrators can post.
* 3 => Only new members can post.
**Changes**: New in Zulip 3.0, replacing the previous
`is_announcement_only` boolean.
message_retention_days:
type: integer
nullable: true
description: |
Number of days that messages sent to this stream will be stored
before being automatically deleted by the [message retention
policy](/help/message-retention-policy). There are two special values:
* `null`, the default, means the stream will inherit the organization
level setting.
* `-1` encodes retaining messages in this stream forever.
**Changes**: New in Zulip 3.0 (feature level 17).
history_public_to_subscribers:
type: boolean
description: |
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
first_message_id:
type: integer
openapi: Edit `/events` OpenAPI specification for validation. Some events in `/events` were incorrectly or incompletely documented. Rectify them.
2020-07-27 16:17:12 +02:00
nullable: true
openapi: Move `subscriptions` schema to the components section. The `subscriptions` has use in multiple endpoints and hence instead of redefining it at every point move it to the the components section for easier reuse.
2020-07-20 13:25:52 +02:00
description: |
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Null is used for streams with no message history.
stream_weekly_traffic:
type: integer
nullable: true
description: |
The average number of messages sent to the stream in recent weeks,
rounded to the nearest integer.
Null means the stream was recently created and there is
insufficient data to estimate the average traffic.
openapi: Extract Emoji Reaction schema from `Messages`. The Emoji Reaction schema is used in multiple place and hence it is better to have it extracted as another schema in `components`.
2020-07-21 14:05:29 +02:00
EmojiReaction:
type: object
additionalProperties: false
properties:
emoji_code:
type: string
description: |
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`.
For example, for `unicode_emoji`, this will be an encoding of the
unicode codepoint.
emoji_name:
type: string
description: |
Name of the emoji.
reaction_type:
type: string
description: |
One of the following values:
* `unicode_emoji`: Unicode emoji (`emoji_code` will be its unicode
codepoint).
* `realm_emoji`: [Custom emoji](/help/add-custom-emoji).
(`emoji_code` will be its ID).
* `zulip_extra_emoji`: Special emoji included with Zulip. Exists to
namespace the `zulip` emoji.
user_id:
type: integer
description: |
The ID of the user who added the reaction.
**Changes**: New in Zulip 3.0 (feature level 2). The `user`
object is deprecated and will be removed in the future.
user:
type: object
additionalProperties: false
deprecated: true
description: |
Dictionary with data on the user who added the reaction, including
the user ID as the `id` field. **Note**: In the [events
API](/api/get-events), this `user` dictionary
confusing had the user ID in a field called `user_id`
instead. We recommend ignoring fields other than the user
ID. **Deprecated** and to be removed in a future release
once core clients have migrated to use the `user_id` field.
properties:
id:
type: integer
description: |
ID of the user.
email:
type: string
description: |
Email of the user.
full_name:
type: string
description: |
Full name of the user.
is_mirror_dummy:
type: boolean
description: |
Whether the user is a mirror dummy.
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
Messages:
type: object
openapi: Document `message` event.
2020-07-28 00:01:59 +02:00
description: |
Object containing details of the message.
openapi: Use third-party validator for schema validation. Our previous OpenAPI schema validator that we implemented ourselves was useful training wheels for our understanding OpenAPI properly, and was mostly correct. But given that we've finally reached the point where our OpenAPI file accurately describes the API, it makes sense to switch to use an official OpenAPI validator. We lose some ability to do exclude rules for particular elements, but those were primarily important for us when we had a lot of them. As part of this change, we need to add `additionalProperties: false` for all of our dictonaries/objects where we've documented every parameter; otherwise the OpenAPI schema checker won't know that we expect every parameter to be documented.
2020-07-01 19:07:31 +02:00
additionalProperties: false
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
properties:
avatar_url:
type: string
nullable: true
description: |
The URL of the user's avatar. Can be null only if client_gravatar was passed,
which means that the user has not uploaded an avatar in Zulip, and the
client should compute the gravatar URL by hashing the
user's email address itself for this user.
client:
type: string
description: |
A Zulip "client" string, describing what Zulip client
sent the message.
content:
type: string
description: |
The content/body of the message.
content_type:
type: string
description: |
The HTTP `content_type` for the message content. This
will be `text/html` or `text/x-markdown`, depending on
whether `apply_markdown` was set.
display_recipient:
oneOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- type: string
- type: array
items:
type: object
additionalProperties: false
properties:
id:
type: integer
description: |
ID of the user.
email:
type: string
description: |
Email of the user.
full_name:
type: string
description: |
Full name of the user.
is_mirror_dummy:
type: boolean
description: |
Whether the user is a mirror dummy.
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
description: |
Data on the recipient of the message;
either the name of a stream or a dictionary containing basic data on
the users who received the message.
id:
type: integer
description: |
The unique message ID. Messages should always be
displayed sorted by ID.
is_me_message:
type: boolean
description: |
Whether the message is a [/me status message][status-messages]
reactions:
type: array
description: |
Data on any reactions to the message.
items:
openapi: Extract Emoji Reaction schema from `Messages`. The Emoji Reaction schema is used in multiple place and hence it is better to have it extracted as another schema in `components`.
2020-07-21 14:05:29 +02:00
$ref: "#/components/schemas/EmojiReaction"
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
recipient_id:
type: integer
description: |
A unique ID for the set of users receiving the
message (either a stream or group of users). Useful primarily
for hashing.
sender_email:
type: string
description: |
The Zulip display email address of the message's sender.
sender_full_name:
type: string
description: |
The full name of the message's sender.
sender_id:
type: integer
description: |
The user ID of the message's sender.
sender_realm_str:
type: string
description: |
A string identifier for the realm the sender is in. Unique only within
the context of a given Zulip server.
E.g. on `example.zulip.com`, this will be `example`.
stream_id:
type: integer
description: |
Only present for stream messages; the ID of the stream.
subject:
type: string
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
The `topic` of the message (only present for stream
messages). The field name is a legacy holdover from when topics were
called "subjects" and will eventually change.
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
topic_links:
type: array
items:
type: string
description: |
Data on any links to be included in the `topic`
line (these are generated by [custom linkification
filters][linkification-filters] that match content in the
message's topic.)
docs: Change next planned major release to 3.0. After some discussion, everyone seems to agree that 3.0 is the more appropriate version number for our next major release. This updates our documentation to reflect that we'll be using 3.0 as our next major release.
2020-06-25 01:25:14 +02:00
**Changes**: New in Zulip 3.0 (feature level 1).
openapi: Document various properties in `EXCLUDED_PROPERTIES`. The `EXCLUDE_PROPERTIES` is a dictionary in `zerver/openapi/openapi.py` which holds the undocumented properties of our API. Document all properties other than: *`delivery_email` which is in another PR. *'events' and 'register'. *'/setting/notification' since its response is about to undergo heavy changes.
2020-06-23 19:29:17 +02:00
Previously, this field was called `subject_links`;
clients are recommended to rename `subject_links`
to `topic_links` if present for compatibility with
older Zulip servers.
submessages:
type: array
items:
type: string
description: |
Data used for certain experimental Zulip integrations.
timestamp:
type: integer
description: |
The UNIX timestamp for when the message was sent,
in UTC seconds.
type:
type: string
description: |
The type of the message: `stream` or `private`.
openapi: Edit `Messages` component to match the `message` event object. The `Messages` schema present in `#/components/schemas` was a combination of all keys possible in any message object used in Zulip. Edit it so that the original `Messages` contains just the keys present in the `message` event. Also make another schema `GetMessages` which adds a few other keys which are received when using `GET /messages`. The message object in the `/zulip-outgoing-webhook` has also been modified and corrected.
2020-07-20 17:28:20 +02:00
GetMessages:
allOf:
- $ref: "#/components/schemas/Messages"
- properties:
flags:
type: array
description: |
The user's [message flags][message-flags] for the message.
items:
type: string
last_edit_timestamp:
type: integer
description: |
The UNIX timestamp for when the message was last edited,
in UTC seconds.
match_content:
type: string
description: |
Only present if keyword search was included among the narrow parameters.
HTML content of a queried message that matches the narrow, with
`<span class="highlight">` elements wrapping the matches for the
search keywords.
match_subject:
type: string
description: |
Only present if keyword search was included among the narrow parameters.
HTML-escaped topic of a queried message that matches the narrow, with
`<span class="highlight">` elements wrapping the matches for the
search keywords.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
User:
type: object
openapi: Use third-party validator for schema validation. Our previous OpenAPI schema validator that we implemented ourselves was useful training wheels for our understanding OpenAPI properly, and was mostly correct. But given that we've finally reached the point where our OpenAPI file accurately describes the API, it makes sense to switch to use an official OpenAPI validator. We lose some ability to do exclude rules for particular elements, but those were primarily important for us when we had a lot of them. As part of this change, we need to add `additionalProperties: false` for all of our dictonaries/objects where we've documented every parameter; otherwise the OpenAPI schema checker won't know that we expect every parameter to be documented.
2020-07-01 19:07:31 +02:00
additionalProperties: false
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
description: |
A dictionary containing basic data on a given Zulip user.
properties:
email:
type: string
description: |
The Zulip API email address of the user or bot.
If you do not have permission to view the email address of the target user,
this will be a fake email address that is usable for the Zulip API but nothing else.
is_bot:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
type: boolean
description: |
A boolean specifying whether the user is a bot or full account.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
avatar_url:
type: string
nullable: true
description: |
URL for the the user's avatar. Will be `null` if the `client_gravatar`
query parameter was set to `True` and the user's avatar is hosted by
the Gravatar provider (i.e. the user has never uploaded an avatar).
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
avatar_version:
type: integer
description: |
Version for the the user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
full_name:
type: string
description: |
Full name of the user or bot, used for all display purposes.
is_admin:
type: boolean
description: |
A boolean specifying whether the user is an organization administrator.
users: Add is_owner field to user objects returned by get endpoints. This commit adds 'is_owner' field to the user object returned by '/users', 'users/{user_id}', and '/users/me' endpoints.
2020-06-01 21:47:18 +02:00
is_owner:
type: boolean
description: |
A boolean specifying whether the user is an organization owner.
If true, is_admin will also be true.
docs: Change next planned major release to 3.0. After some discussion, everyone seems to agree that 3.0 is the more appropriate version number for our next major release. This updates our documentation to reflect that we'll be using 3.0 as our next major release.
2020-06-25 01:25:14 +02:00
**Changes**: New in Zulip 3.0 (feature level 8).
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
bot_type:
type: integer
nullable: true
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
An integer describing the type of bot:
* `null` if the user isn't a bot.
* `1` for a `Generic` bot.
* `2` for an `Incoming webhook` bot.
* `3` for an `Outgoing webhook` bot.
* `4` for an `Embedded` bot.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
user_id:
type: integer
description: |
The unique ID of the user.
bot_owner_id:
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
type: integer
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
nullable: true
description: |
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
If the user is a bot (i.e. `is_bot` is `True`),
`bot_owner` is the user ID of the bot's owner (usually, whoever
created the bot).
Will be null for legacy bots that do not have an owner.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
docs: Change next planned major release to 3.0. After some discussion, everyone seems to agree that 3.0 is the more appropriate version number for our next major release. This updates our documentation to reflect that we'll be using 3.0 as our next major release.
2020-06-25 01:25:14 +02:00
**Changes**: New in Zulip 3.0 (feature level
openapi: Fix some zulip.yaml return values description. There are several places where the return values description is better in the api docs than in the zulip.yaml file. Import such changes to zulip.yaml before we replace the current hacky API docs with the zulip.yaml content.
2020-05-29 23:13:25 +02:00
1). In previous versions, there was a `bot_owner` field
containing the email address of the bot's owner.
openapi_responses: Fix get_users and get_user.
2020-05-26 12:50:27 +02:00
is_active:
type: boolean
description: |
A boolean specifying whether the user account has been deactivated.
is_guest:
type: boolean
description: |
A boolean specifying whether the user is a guest user.
timezone:
type: string
description: |
The time zone of the user.
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
date_joined:
type: string
description: |
The time the user account was created.
openapi: Document `delivery_email` property.
2020-06-23 20:15:01 +02:00
delivery_email:
type: string
description: |
The user's real email address. This field is present only if
[email address visibility](/help/restrict-visibility-of-email-addresses) is
limited and you are an administrator with access to real email addresses
under the configured policy.
openapi: Fix various errors in OpenAPI declarations. Based on original work by Aditya Verma to tag places where our API documentation was inaccurate / incomplete.
2020-06-02 20:26:37 +02:00
profile_data:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$ref: "#/components/schemas/profile_data"
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
profile_data:
type: object
description: |
A dictionary containing custom profile field data for the user. Each entry
maps the integer ID of a custom profile field in the organization to a
dictionary containing the user's data for that field. Generally the data
includes just a single `value` key; for those custom profile fields
supporting markdown, a `rendered_value` key will also be present.
additionalProperties:
type: object
openapi: Use third-party validator for schema validation. Our previous OpenAPI schema validator that we implemented ourselves was useful training wheels for our understanding OpenAPI properly, and was mostly correct. But given that we've finally reached the point where our OpenAPI file accurately describes the API, it makes sense to switch to use an official OpenAPI validator. We lose some ability to do exclude rules for particular elements, but those were primarily important for us when we had a lot of them. As part of this change, we need to add `additionalProperties: false` for all of our dictonaries/objects where we've documented every parameter; otherwise the OpenAPI schema checker won't know that we expect every parameter to be documented.
2020-07-01 19:07:31 +02:00
additionalProperties: false
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
description: |
'{id}': Object with data about what value user filled in the custom
profile field with id `id`.
properties:
value:
type: string
description: |
User's personal value for this custom profile field.
rendered_value:
type: string
description: |
The `value` rendered in HTML. Will only be present for
custom profile field types that support markdown rendering.
This user-generated HTML content should be rendered
using the same CSS and client-side security protections
as are used for message content.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
JsonResponse:
type: object
openapi: Use third-party validator for schema validation. Our previous OpenAPI schema validator that we implemented ourselves was useful training wheels for our understanding OpenAPI properly, and was mostly correct. But given that we've finally reached the point where our OpenAPI file accurately describes the API, it makes sense to switch to use an official OpenAPI validator. We lose some ability to do exclude rules for particular elements, but those were primarily important for us when we had a lot of them. As part of this change, we need to add `additionalProperties: false` for all of our dictonaries/objects where we've documented every parameter; otherwise the OpenAPI schema checker won't know that we expect every parameter to be documented.
2020-07-01 19:07:31 +02:00
additionalProperties: false
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:
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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonResponse"
- required:
- result
- msg
- properties:
result:
enum:
- success
msg:
type: string
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- required:
- api_key
- email
- properties:
api_key:
type: string
description: |
The API key that can be used to authenticate as the requested user.
email:
type: string
description: |
The email address of the user who owns the API key
- example:
{
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
"api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv",
"email": "iago@zulip.com",
"msg": "",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "success",
}
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
CodedError:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
- properties:
code:
type: string
description: |
A string that identifies the error.
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
BadEventQueueIdError:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
- properties:
queue_id:
type: string
description: |
The string that identifies the invalid event queue.
- example:
{
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
"code": "BAD_EVENT_QUEUE_ID",
"msg": "Bad event queue id: 1518820930:1",
"queue_id": "1518820930:1",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
InvalidMessageError:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
raw_content:
type: string
description: |
The raw content of the message.
- example:
{
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
"msg": "Invalid message(s)",
"code": "BAD_REQUEST",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"result": "error",
}
api docs: Create the NonExistingStreamError schema definition.
2018-06-21 02:25:29 +02:00
NonExistingStreamError:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
api docs: Create the NonExistingStreamError schema definition.
2018-06-21 02:25:29 +02:00
- 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:
{
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"code": "STREAM_DOES_NOT_EXIST",
"msg": "Stream 'nonexistent_stream' does not exist",
"result": "error",
"stream": "nonexistent_stream",
api docs: Create the NonExistingStreamError schema definition.
2018-06-21 02:25:29 +02:00
}
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
AddSubscriptionsResponse:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonSuccess"
- properties:
subscribed:
type: object
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
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.
additionalProperties:
description: |
`{email_address}`: List of the names of the streams that were subscribed
to as a result of the query.
type: array
items:
type: string
already_subscribed:
type: object
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
description: |
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
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.
additionalProperties:
description: |
{email_address}`: List of the names of the streams that the user is
already subscribed to.
type: array
items:
type: string
unauthorized:
openapi: Forbid opaque objects from OpenAPI documentation. Objects whose properties are not described were validated by the current validator. Edit it so that objects with no `properties` or `additionalProperties` attribute i.e. opaque objects get invalidated. Also make changes in zulip.yaml to fix any opaque objects (tweaked by tabbott to edit the documentation for better clarity).
2020-06-03 00:16:02 +02:00
type: array
items:
type: string
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
description: |
A list of names of streams that the requesting user/bot was not
authorized to subscribe to. Only present if `authorization_errors_fatal=false`.
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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/JsonError"
prettier: Disable bracketSpacing. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-15 20:45:38 +02:00
- example: {"msg": "Invalid API key", "result": "error"}
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
MissingArgumentError:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
- properties:
var_name:
type: string
description: |
It contains the information about the missing parameter.
- example:
{
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
"code": "REQUEST_VARIABLE_MISSING",
"msg": "Missing 'content' argument",
"result": "error",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"var_name": "content",
}
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
UserNotAuthorizedError:
allOf:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
- $ref: "#/components/schemas/CodedError"
- example:
{
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
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
"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:
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
$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).
openapi_docs: Replace `argument` with `parameter`. The term `parameter` is a better word than `argument` for data passed to an API endpoint; this is why OpenAPI uses in their terminology. Replace `argument` with `parameter` in the API docs to improve their readability. Fixes #15435.
2020-06-18 15:35:25 +02:00
If you do not specify this parameter, you will receive all
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
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']`
openapi: Correctly encode object and array parameters. The current description of object and array parameters in zulip.yaml is wrong and renders incorrect requests on using OpenAPI tools such as SwaggerIO, etc. Fix it by encoding it correctly and changing tests accordingly. Fixes #14380.
2020-06-27 19:23:50 +02:00
content:
application/json:
schema:
type: array
items:
type: string
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
example: ["message"]
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
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: |
openapi: Fix documentation of narrow parameter. The narrow parameter was incorrectly documented as a one-level array rather than an array of arrays, and the tests incorrectly expected this due to a combination of design and implementation bugs. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-06-13 06:26:41 +02:00
A JSON-encoded array of arrays 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.
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
Default is `[]`.
openapi: Correctly encode object and array parameters. The current description of object and array parameters in zulip.yaml is wrong and renders incorrect requests on using OpenAPI tools such as SwaggerIO, etc. Fix it by encoding it correctly and changing tests accordingly. Fixes #14380.
2020-06-27 19:23:50 +02:00
content:
application/json:
schema:
type: array
items:
type: array
items:
type: string
default: []
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
example: [["stream", "Denmark"]]
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
required: false
api_docs: Add "GroupId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "group_id" in components.
2020-04-18 10:54:51 +02:00
GroupId:
name: group_id
in: path
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The ID of the target user group.
api_docs: Add "GroupId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "group_id" in components.
2020-04-18 10:54:51 +02:00
schema:
type: integer
example: 42
required: true
api_docs: Add "Topic" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "topic" in components.
2020-04-18 11:14:08 +02:00
Topic:
name: topic
in: query
description: |
The topic of the message. Only required for stream messages
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
(`type="stream"`), ignored otherwise.
Maximum length of 60 characters.
api docs: Document changes in API topic encoding.
2020-06-25 21:40:55 +02:00
**Changes**: New in Zulip 2.0. Previous Zulip releases encoded
this as `subject`, which is currently a deprecated alias.
api_docs: Add "Topic" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "topic" in components.
2020-04-18 11:14:08 +02:00
schema:
type: string
example: Castle
api_docs: Add "QueueId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "queue_id" in components.
2020-04-18 17:35:53 +02:00
QueueId:
name: queue_id
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The ID of an event queue that was previously registered via `POST
/api/v1/register` (see [Register a queue](/api/register-queue)).
api_docs: Add "QueueId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "queue_id" in components.
2020-04-18 17:35:53 +02:00
schema:
type: string
example: 1375801870:2942
required: true
api_docs: Add "Stream" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream" in components.
2020-04-18 17:59:13 +02:00
Stream:
name: stream
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The name of the stream to access.
api_docs: Add "Stream" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream" in components.
2020-04-18 17:59:13 +02:00
schema:
type: string
example: Denmark
api_docs: Add "StreamIdInQuery" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in query) in components.
2020-04-19 10:01:44 +02:00
StreamIdInQuery:
name: stream_id
in: query
description: |
The ID of the stream to access.
schema:
type: integer
example: 42
api_docs: Add "StreamIdInPath" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_id" (in path) in components.
2020-04-19 10:30:30 +02:00
StreamIdInPath:
name: stream_id
in: path
description: |
The ID of the stream to access.
schema:
type: integer
example: 42
required: true
api_docs: Add "ClientGravatar" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "client_gravatar" in components.
2020-04-19 11:21:51 +02:00
ClientGravatar:
name: client_gravatar
in: query
description: |
Whether the client supports computing gravatars URLs. If
enabled, `avatar_url` will be included in the response only
if there is a Zulip avatar, and will be `null` for users who
are using gravatar as their avatar. This option
significantly reduces the compressed size of user data,
since gravatar URLs are long, random strings and thus do not
compress well. The `client_gravatar` field is set to `true` if
clients can compute their own gravatars.
schema:
type: boolean
default: false
example: true
openapi: Improve `/messages/{message_id}` PATCH documentation. We extract OptionalContent and RequiredContent since some endpoints require it and other don't. In an ideal world, we'd have a better way to express these small variants.
2020-07-10 00:02:44 +02:00
RequiredContent:
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
name: content
in: query
description: |
The content of the message. Maximum message size of 10000 bytes.
schema:
type: string
example: Hello
required: true
openapi: Improve `/messages/{message_id}` PATCH documentation. We extract OptionalContent and RequiredContent since some endpoints require it and other don't. In an ideal world, we'd have a better way to express these small variants.
2020-07-10 00:02:44 +02:00
OptionalContent:
name: content
in: query
description: |
The content of the message. Maximum message size of 10000 bytes.
schema:
type: string
example: Hello
api_docs: Add "MessageId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "message_id" in components.
2020-04-20 16:46:14 +02:00
MessageId:
name: message_id
in: path
description: |
The target message's ID.
schema:
type: integer
example: 42
required: true
api_docs: Add "UserId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "user_id" in components.
2020-04-21 21:44:21 +02:00
UserId:
name: user_id
in: path
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The target user's ID.
api_docs: Add "UserId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "user_id" in components.
2020-04-21 21:44:21 +02:00
schema:
type: integer
populate_db: Add new admin user as 'Desdemona'. This commit adds a second admin user named 'Desdemona' to dev and test database.
2020-05-17 18:46:14 +02:00
example: 12
api_docs: Add "UserId" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "user_id" in components.
2020-04-21 21:44:21 +02:00
required: true
api_docs: Add "StreamPostPolicy" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_post_policy" in components.
2020-04-21 21:53:33 +02:00
StreamPostPolicy:
name: stream_post_policy
in: query
description: |
Policy for which users can post messages to the stream.
* 1 => Any user can post.
* 2 => Only administrators can post.
* 3 => Only new members can post.
docs: Change next planned major release to 3.0. After some discussion, everyone seems to agree that 3.0 is the more appropriate version number for our next major release. This updates our documentation to reflect that we'll be using 3.0 as our next major release.
2020-06-25 01:25:14 +02:00
**Changes**: New in Zulip 3.0, replacing the previous
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
`is_announcement_only` boolean.
api_docs: Add "StreamPostPolicy" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "stream_post_policy" in components.
2020-04-21 21:53:33 +02:00
schema:
type: integer
default: 1
example: 2
required: false
api_docs: Add HistoryPublicToSubscribers component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "history_public_to_subscribers" in components.
2020-04-21 21:56:47 +02:00
HistoryPublicToSubscribers:
name: history_public_to_subscribers
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
Whether the stream's message history should be available to
newly subscribed members, or users can only access messages
they actually received while subscribed to the stream.
Corresponds to the [shared history](/help/stream-permissions)
option in documentation.
api_docs: Add HistoryPublicToSubscribers component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "history_public_to_subscribers" in components.
2020-04-21 21:56:47 +02:00
schema:
type: boolean
example: false
required: false
api_docs: Add "IncludeSubscribers" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "IncludeSubscribers" in components.
2020-04-21 22:14:11 +02:00
IncludeSubscribers:
name: include_subscribers
in: query
description: |
Whether each returned stream object should include a `subscribers`
field containing a list of the user IDs of its subscribers.
(This may be significantly slower in organizations with
thousands of users subscribed to many streams.)
**Changes**: New in Zulip 2.1.0.
schema:
type: boolean
default: false
example: true
api_docs: Add "EmojiName" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_name" in components.
2020-04-21 22:24:18 +02:00
EmojiName:
name: emoji_name
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
The target emoji's human-readable name.
api_docs: Add "EmojiName" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_name" in components.
2020-04-21 22:24:18 +02:00
To find an emoji's name, hover over a message to reveal
three icons on the right, then click the smiley face icon.
Images of available reaction emojis appear. Hover over the
emoji you want, and note that emoji's text name.
schema:
type: string
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
example: "octopus"
api_docs: Add IncludeCustomProfileFields component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "include_custom_profile_fields" in components.
2020-04-21 22:26:12 +02:00
IncludeCustomProfileFields:
name: include_custom_profile_fields
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
Whether the client wants [custom profile field](/help/add-custom-profile-fields)
data to be included in the response.
api_docs: Add IncludeCustomProfileFields component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "include_custom_profile_fields" in components.
2020-04-21 22:26:12 +02:00
**Changes**: New in Zulip 2.1.0. Previous versions do no offer these
data via the API.
schema:
type: boolean
default: false
example: true
api_docs: Add "Principals" component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "principals" in components.
2020-04-21 22:27:56 +02:00
Principals:
name: principals
in: query
description: |
stream: Add support for sending user_id to endpoint when subscribing users. This commit modifies the backend to accept user ids when subscribing users to streams. It also migrates all existing tests to use this API, aside from a small set of tests for the legacy API.
2020-04-09 19:07:57 +02:00
A list of user ids (preferred) or Zulip display email
addresses of the users to be subscribed to or unsubscribed
openapi_docs: Replace `argument` with `parameter`. The term `parameter` is a better word than `argument` for data passed to an API endpoint; this is why OpenAPI uses in their terminology. Replace `argument` with `parameter` in the API docs to improve their readability. Fixes #15435.
2020-06-18 15:35:25 +02:00
from the streams specified in the `subscriptions` parameter. If
stream: Add support for sending user_id to endpoint when subscribing users. This commit modifies the backend to accept user ids when subscribing users to streams. It also migrates all existing tests to use this API, aside from a small set of tests for the legacy API.
2020-04-09 19:07:57 +02:00
not provided, then the requesting user/bot is subscribed.
docs: Change next planned major release to 3.0. After some discussion, everyone seems to agree that 3.0 is the more appropriate version number for our next major release. This updates our documentation to reflect that we'll be using 3.0 as our next major release.
2020-06-25 01:25:14 +02:00
**Changes**: The integer format is new in Zulip 3.0 (Feature level 9).
openapi: Correctly encode object and array parameters. The current description of object and array parameters in zulip.yaml is wrong and renders incorrect requests on using OpenAPI tools such as SwaggerIO, etc. Fix it by encoding it correctly and changing tests accordingly. Fixes #14380.
2020-06-27 19:23:50 +02:00
content:
application/json:
schema:
type: array
items:
oneOf:
- type: string
- type: integer
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
example: ["ZOE@zulip.com"]
api_docs: Add "ReactionType" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "reaction_type" in components.
2020-04-21 22:29:35 +02:00
ReactionType:
name: reaction_type
in: query
description: |
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
If an app is adding/removing a vote on an existing reaction,
it should pass this parameter using the value the server provided
for the existing reaction for specificity. Supported values:
* `unicode_emoji`: Unicode emoji (`emoji_code` will be its unicode codepoint).
* `realm_emoji`: Custom emoji. (`emoji_code` will be its ID).
* `zulip_extra_emoji`: Special emoji included with Zulip. Exists to
namespace the `zulip` emoji.
docs: Change next planned major release to 3.0. After some discussion, everyone seems to agree that 3.0 is the more appropriate version number for our next major release. This updates our documentation to reflect that we'll be using 3.0 as our next major release.
2020-06-25 01:25:14 +02:00
**Changes**: In Zulip 3.0 (feature level 2), this become
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
optional for [custom emoji](/help/add-custom-emoji);
previously, this endpoint assumed `unicode_emoji` if this
parameter was not specified.
api_docs: Add "ReactionType" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "reaction_type" in components.
2020-04-21 22:29:35 +02:00
schema:
type: string
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
example: "unicode_emoji"
api_docs: Add "ReactionType" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "reaction_type" in components.
2020-04-21 22:29:35 +02:00
required: false
api_docs: Add "EmojiCode" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_code" in components.
2020-04-24 03:02:15 +02:00
EmojiCode:
name: emoji_code
in: query
description: |
openapi: Fix validate_against_openapi_schema nested object validation. We had a bug in `validate_against_openapi_schema` that prevented it from correctly inspecting nested arrays. Fix the bug and address all the exceptions, either via EXCLUDE_PROPERTIES or fixing them when simple. Also add a test case for nested verification.
2020-06-20 19:25:32 +02:00
A unique identifier, defining the specific emoji codepoint requested,
api docs: Improve a few common OpenAPI descriptions. This fixes a few regressions of documentation introduced earlier in this branch.
2020-05-06 01:59:58 +02:00
within the namespace of the `reaction_type`.
For most API clients, you won't need this, but it's important
for Zulip apps to handle rare corner cases when
adding/removing votes on an emoji reaction added previously by
another user.
If the existing reaction was added when the Zulip server was
using a previous version of the emoji data mapping between
Unicode codepoints and human-readable names, sending the
`emoji_code` in the data for the original reaction allows the
Zulip server to correctly interpret your upvote as an upvote
api_docs: Add "EmojiCode" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_code" in components.
2020-04-24 03:02:15 +02:00
rather than a reaction with a "diffenent" emoji.
schema:
type: string
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
example: "1f419"
api_docs: Add "EmojiCode" common component. To facilitate re-use of the same parameters in other paths, this commit store the content of the parameter "emoji_code" in components.
2020-04-24 03:02:15 +02:00
required: false
streams: Add API for changing stream-level message_retention_days. This commit adds backend support for setting message_retention_days while creating streams and updating it for an existing stream. We only allow organization owners to set/update it for a stream. 'message_retention_days' field for a stream existed previously also, but there was no way to set it while creating streams or update it for an exisiting streams using any endpoint.
2020-06-14 18:57:02 +02:00
MessageRetentionDays:
name: message_retention_days
in: query
description: |
Number of days that messages sent to this stream will be stored
before being automatically deleted by the [message retention
policy](/help/message-retention-policy). Two special string format
values are supported:
* "realm_default" => Return to the organization-level setting.
* "forever" => Retain messages forever.
docs: Change next planned major release to 3.0. After some discussion, everyone seems to agree that 3.0 is the more appropriate version number for our next major release. This updates our documentation to reflect that we'll be using 3.0 as our next major release.
2020-06-25 01:25:14 +02:00
**Changes**: New in Zulip 3.0 (feature level 17).
streams: Add API for changing stream-level message_retention_days. This commit adds backend support for setting message_retention_days while creating streams and updating it for an existing stream. We only allow organization owners to set/update it for a stream. 'message_retention_days' field for a stream existed previously also, but there was no way to set it while creating streams or update it for an exisiting streams using any endpoint.
2020-06-14 18:57:02 +02:00
schema:
oneOf:
- type: string
- type: integer
lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-07-01 21:19:49 +02:00
example: "20"
streams: Add API for changing stream-level message_retention_days. This commit adds backend support for setting message_retention_days while creating streams and updating it for an existing stream. We only allow organization owners to set/update it for a stream. 'message_retention_days' field for a stream existed previously also, but there was no way to set it while creating streams or update it for an exisiting streams using any endpoint.
2020-06-14 18:57:02 +02:00
required: false