From 65d60f4a25e3efa8d0f4d70b4bac57011d6b6bde Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Sun, 1 Aug 2021 15:07:53 -0700 Subject: [PATCH] api docs: Improve documentation for user_settings transition. --- templates/zerver/api/changelog.md | 32 +++-- zerver/openapi/zulip.yaml | 225 ++++++++++++++++++------------ 2 files changed, 156 insertions(+), 101 deletions(-) diff --git a/templates/zerver/api/changelog.md b/templates/zerver/api/changelog.md index d18642d505..7c155eb0c9 100644 --- a/templates/zerver/api/changelog.md +++ b/templates/zerver/api/changelog.md @@ -13,22 +13,24 @@ below features are supported. **Feature level 89** -* [`GET /events`](/api/get-events): Introduced new event type - `user_settings`. The previous `update_display_settings` and - `update_global_notifications` event types are still supported - for backwards compatibility, but will be removed in future. -* [`POST /register`](/api/register-queue): Added the new - `user_settings_object` property to supported `client_capabilities`. -* [`GET /events`](/api/get-events): `update_display_settings` and - `update_global_notifications` are sent only when `user_settings_object` - is not included in the `client_capabilities` when registering the - event queue. +* [`GET /events`](/api/get-events): Introduced the `user_settings` + event type, unifying and replacing the previous + `update_display_settings` and `update_global_notifications` event + types. The legacy event types are still supported for backwards + compatibility, but will be removed in a future release. * [`POST /register`](/api/register-queue): Added `user_settings` field - in the response, which is a dictionary containing all the user settings. -* [`POST /register`](/api/register-queue): User's personal settings in - the top-level object are included in response only when `user_settings_object` - is not included in the `client_capabilities` when registering the event - queue. + in the response, which is a dictionary containing all the user's + personal settings. For backwards-compatibility, individual settings + will still appear in the top-level response for clients don't + support the `user_settings_object` client capability. +* [`POST /register`](/api/register-queue): Added the + `user_settings_object` property to supported `client_capabilities`. + When enabled, the server will not include a duplicate copy of + personal settings in the top-level response. +* [`GET /events`](/api/get-events): `update_display_settings` and + `update_global_notifications` events now only sent to clients that + did not include `user_settings_object` in their + `client_capabilities` when the event queue was created. **Feature level 88** diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 0bfd85dee4..6f1cc1a3c4 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -241,13 +241,14 @@ paths: } - type: object description: | - Event sent to a user's clients when that user's display settings - have changed with an additional rule that it is only sent to - clients that did not include `user_settings_object` in their - `client_capabilities` when registering the event queue. + Event sent to clients that that have requested the + `update_display_settings` event type and did not include + `user_settings_object` in their `client_capabilities` when + registering the event queue. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), replaced by - the `user_settings` event type. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and process the `user_settings` event type instead. deprecated: true properties: id: @@ -290,8 +291,9 @@ paths: `user_settings_object` in their `client_capabilities` when registering the event queue. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), replaced by - the `user_settings` event type. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and process the `user_settings` event type instead. deprecated: true properties: id: @@ -8237,8 +8239,9 @@ paths: 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 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 @@ -8246,7 +8249,9 @@ paths: 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 + 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. @@ -8257,11 +8262,12 @@ paths: `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). * `stream_typing_notifications`: Boolean for whether the client supports stream typing notifications. - +
New in Zulip 4.0 (feature level 58). This capability is for backwards-compatibility; it will be required in a future server release. @@ -8270,8 +8276,17 @@ paths: `user_settings` event type. If False, the server will additionally send the legacy `update_display_settings` and `update_global_notifications` event types for backwards-compatibility with clients that predate this API migration. - - New in Zulip 4.0 (feature level 89). This capability is for +
+
+ Because the feature level 89 API changes were merged together, clients can + safely make a request with this client capability and requesting all of the + `user_settings`, `update_display_settings`, and + `update_global_notifications` event types, and get exactly one copy of + settings data on any server version. (And then use the `zulip_feature_level` + in the `/register` response or the presence/absence of a `user_settings` key + to determine where to look). +
+ New in Zulip 5.0 (feature level 89). This capability is for backwards-compatibility; it will be removed in a future server release. content: application/json: @@ -9289,8 +9304,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_digest_emails: deprecated: true type: boolean @@ -9303,8 +9319,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_login_emails: deprecated: true type: boolean @@ -9317,8 +9334,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_marketing_emails: deprecated: true type: boolean @@ -9331,8 +9349,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. email_notifications_batching_period_seconds: deprecated: true type: integer @@ -9345,8 +9364,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_offline_email_notifications: deprecated: true type: boolean @@ -9359,8 +9379,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_offline_push_notifications: deprecated: true type: boolean @@ -9373,8 +9394,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_online_push_notifications: deprecated: true type: boolean @@ -9387,8 +9409,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_sounds: deprecated: true type: boolean @@ -9401,8 +9424,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_stream_desktop_notifications: deprecated: true type: boolean @@ -9415,8 +9439,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_stream_email_notifications: deprecated: true type: boolean @@ -9429,8 +9454,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_stream_push_notifications: deprecated: true type: boolean @@ -9443,8 +9469,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_stream_audible_notifications: deprecated: true type: boolean @@ -9457,8 +9484,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. wildcard_mentions_notify: deprecated: true type: boolean @@ -9471,8 +9499,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. message_content_in_email_notifications: deprecated: true type: boolean @@ -9485,8 +9514,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. notification_sound: deprecated: true type: string @@ -9499,8 +9529,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. pm_content_in_desktop_notifications: deprecated: true type: boolean @@ -9513,8 +9544,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. desktop_icon_count_display: deprecated: true type: integer @@ -9527,8 +9559,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. realm_name_in_notifications: deprecated: true type: boolean @@ -9541,8 +9574,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. presence_enabled: deprecated: true type: boolean @@ -9555,8 +9589,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. available_notification_sounds: deprecated: true type: array @@ -9571,8 +9606,9 @@ paths: this Zulip server. Only relevant to support UI for configuring notification sounds. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. color_scheme: deprecated: true type: integer @@ -9586,8 +9622,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. default_language: deprecated: true type: string @@ -9601,8 +9638,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. demote_inactive_streams: deprecated: true type: integer @@ -9616,8 +9654,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. dense_mode: deprecated: true type: boolean @@ -9632,8 +9671,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. emojiset: deprecated: true type: string @@ -9647,8 +9687,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. enable_drafts_synchronization: deprecated: true type: boolean @@ -9661,8 +9702,11 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. New in Zulip 5.0 (feature level 87). + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. + + New in Zulip 5.0 (feature level 87). fluid_layout_width: deprecated: true type: boolean @@ -9676,8 +9720,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. default_view: deprecated: true type: string @@ -9694,8 +9739,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. high_contrast_mode: deprecated: true type: boolean @@ -9709,8 +9755,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. left_side_userlist: deprecated: true type: boolean @@ -9726,8 +9773,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. starred_message_counts: deprecated: true type: boolean @@ -9742,8 +9790,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. timezone: deprecated: true type: string @@ -9758,8 +9807,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. translate_emoticons: deprecated: true type: boolean @@ -9774,8 +9824,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. twenty_four_hour_time: deprecated: true type: boolean @@ -9790,8 +9841,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. emojiset_choices: deprecated: true description: | @@ -9808,8 +9860,9 @@ paths: See [PATCH /settings](/api/update-settings) for details on the meaning of this setting. - **Changes**: Deprecated in Zulip 5.0 (feature level 89), clients should - use `user_settings` dictionary instead. + **Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients + connecting to newer servers should declare the `user_settings_object` + client capability and access the `user_settings` object instead. type: array items: type: object