diff --git a/templates/zerver/api/changelog.md b/templates/zerver/api/changelog.md new file mode 100644 index 0000000000..75076c0e8a --- /dev/null +++ b/templates/zerver/api/changelog.md @@ -0,0 +1,118 @@ +# Changelog + +This page documents changes to the Zulip Server API over time. + +The recommended way for a client like the Zulip mobile or desktop apps +that needs to support interaction with a wide range of different Zulip +server versions is to check the `zulip_feature_level` parameter in the +`/register` and `/server_settings` responses to determine which of the +below features are supported. + +## Changes in Zulip 2.2 + +**Feature level 2**: + +* [`POST /messages/{message_id}/reactions`](/api/add-emoji-reaction): + The `emoji_type` parameter is optional; the server will guess the + emoji_type if it is not specified (checking custom emoji, then + unicode emoji for any with the provided name). +* `reactions` objects returned by the API (both in `GET /messages` and + in `GET /events`) now include the user who reacted in a top-level + `user_id` field. The legacy `user` dictionary (which had + inconsistent format between those two endpoints) is deprecated. + +**Feature level 1**: + +* [`GET /server_settings`](/api/server-settings): Added + `zulip_feature_level`, which can be used by clients to detect which + of the features described in this changelog are supported. +* [`POST /register`](/api/register-queue): Added `zulip_feature_level` + to the response if `zulip_version` is among the requested + `event_types`. +* [`GET /users`](/api/get-all-users): User objects for bots now + contain a `bot_owner_id`, replacing the previous `bot_owner` field + (which had the email address of the bot owner). +* [`GET /users/{user_id}`](/api/get-user): Endpoint added. +* [`GET /messages`](/api/get-messages): Add support for string-format + values for the `anchor` parameter, deprecating and replacing the + `use_first_unread_anchor` parameter. +* [`GET /messages`](/api/get-messages) and [`GET + /events`](/api/get-events-from-queue): Message objects now use + `topic_links` rather than `subject_links` to indicate links either + present in the topic or generated by Linkifiers applied to the topic. +* [`POST /users/me/subscriptions`](/api/add-subscriptions): Replaced + `is_announcement_only` boolean with `stream_post_policy` enum for + specifying who can post to a stream. +* [`PATCH /streams/{stream_id}`](/api/update-stream): Replaced + `is_announcement_only` boolean with `stream_post_policy` enum for + specifying who can post to a stream. +* [`GET /streams`](/api/get-all-streams): Replaced + `is_announcement_only` boolean with `stream_post_policy` enum for + specifying who can post to a stream. +* `GET /api/v1/user_uploads`: Added new endpoint for requesting a + temporary URL for an uploaded file that does not require + authentication to access (e.g. for passing from a Zulip desktop, + mobile, or terminal app to the user's default browser). +* Added `EMAIL_ADDRESS_VISIBILITY_NOBODY` possible value for + `email_address_visibility`. +* Added `private_message_policy` realm setting. +* `muted_topic` objects now are a 3-item tuple: (`stream_id`, `topic`, + `date_muted`). Previously, they were a 2-item tuple. +* `GitLab` authentication is now available. +* Added `None` as a video call provider option. + +## Changes in Zulip 2.1 + +* [`GET /users`](/api/get-all-users): Added `include_custom_profile_fields` + to request custom profile field data. +* [`GET /users/me`](/api/get-profile): Added `avatar_url` field, + containing the user's avatar URL, to the response. +* [`GET /users/me/subscriptions`](/api/get-subscribed-streams): Added + `include_subscribers` parameter controlling whether data on the + other subscribers is included. Previous behavior was to always send + subscriber data. +* [`GET /users/me/subscriptions`](/api/get-subscribed-streams): + Stream-level notification settings like `push_notifications` were + changed to be nullable boolean fields (true/false/null), with `null` + meaning that the stream inherits the organization-level default. + Previously, the only values were true/false. A client communicates + support for this feature using `client_capabilities`. +* [`GET /users/me/subscriptions`](/api/get-subscribed-streams): Added + `wildcard_mentions_notify` notification setting, with the same + global-plus-stream-level-override model as other notification settings. +* [`GET /server_settings`](/api/server-settings): Added + `external_authentication_methods` structure, used to display login + buttons nicely in the mobile apps. +* Added `first_message_id` field to Stream objects. This is helpful + for determining whether the stream has any messages older than a + window cached in a client. +* Added `is_web_public` field to Stream objects. This field is + intended to support web-public streams. +* Added `/export/realm` endpoints for triggering a data export. +* `PATCH /realm`: Added `invite_to_stream_policy`, + `create_stream_policy`, `digest_emails_enabled`, `digest_weekday`, + `user_group_edit_policy`, and `avatar_changes_disabled` organization settings. +* Added `fluid_layout_width`, `desktop_icon_count_display`, and + `demote_inactive_streams` display settings. +* `enable_stream_sounds` was renamed to + `enable_stream_audible_notifications`. +* Deprecated `is_home_view`, replacing it with the more readable + `is_muted` (with the opposite meaning). +* Custom profile fields: Added `EXTERNAL_ACCOUNT` field type. + +## Changes in Zulip 2.0 + +* [`POST /messages`](/api/send-message): Added support for using user + IDs and stream IDs for specifying the recipients of a message. +* [`POST /typing`](/api/typing): Added support for specifying the + recipients with user IDs, deprecating the original API of specifying + them using email addresses. + +------------------ + +## Changes not yet stabilized + +* [`POST /register`](/api/register-queue): Added `slim_presence` + parameter. Changes the format of presence events, but is still + being changed and should not be used by clients. +* `message_retention_days` field in stream objects. diff --git a/templates/zerver/api/get-all-users.md b/templates/zerver/api/get-all-users.md index 36353bfcbc..266f67b2e6 100644 --- a/templates/zerver/api/get-all-users.md +++ b/templates/zerver/api/get-all-users.md @@ -63,10 +63,11 @@ You may pass the `client_gravatar` query parameter as follows: `2` for an `Incoming webhook` bot. `3` for an `Outgoing webhook` bot. `4` for an `Embedded` bot. * `user_id`: The ID of the user. - * `bot_owner_id`: 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). - **Changes**: New in Zulip 2.2. In previous versions, there was a `bot_owner` - field containing the email address of the bot's owner. + * `bot_owner_id`: 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). **Changes**: New in Zulip 2.2 (feature level + 1). In previous versions, there was a `bot_owner` field + containing the email address of the bot's owner. * `is_active`: A boolean specifying whether the user is active or not. * `is_guest`: A boolean specifying whether the user is a guest user or not. * `timezone`: The time zone of the user. diff --git a/templates/zerver/api/get-messages.md b/templates/zerver/api/get-messages.md index bece150017..08a0a3fe41 100644 --- a/templates/zerver/api/get-messages.md +++ b/templates/zerver/api/get-messages.md @@ -81,8 +81,8 @@ present in all Zulip API responses). * `reaction_type`: If the reaction uses a [custom emoji](/help/add-custom-emoji), `reaction_type` will be set to `realm_emoji`. * `user_id`: The ID of the user who added the reaction. - **Changes**: New in Zulip 2.2. The `user` object is - deprecated and will be removed in the future. + **Changes**: New in Zulip 2.2 (feature level 2). The `user` + object is deprecated and will be removed in the future. * `user`: Dictionary with data on the user who added the reaction, including the user ID as the `id` field. **Note**: In the [events API](/api/get-events-from-queue), this `user` dictionary @@ -104,12 +104,12 @@ present in all Zulip API responses). messages). The name is a legacy holdover from when topics were called "subjects". * `topic_links`: Data on any links to be included in the `topic` - line (these are generated by - [custom linkification filters][linkification-filters] that match - content in the message's topic.) **Changes**: Before Zulip 2.2, - this field was called `subject_links`; clients are recommended - to rename `subject_links` to `topic_links` if present for - compatibility with older Zulip servers. + line (these are generated by [custom linkification + filters][linkification-filters] that match content in the + message's topic.) **Changes**: New in Zulip 2.2 (feature level + 1). Previously, this field was called `subject_links`; clients + are recommended to rename `subject_links` to `topic_links` if + present for compatibility with older Zulip servers. * `submessages`: Data used for certain experimental Zulip integrations. * `timestamp`: The UNIX timestamp for when the message was sent, in UTC seconds. diff --git a/templates/zerver/api/server-settings.md b/templates/zerver/api/server-settings.md index 8559cfb54d..76cf1da6e6 100644 --- a/templates/zerver/api/server-settings.md +++ b/templates/zerver/api/server-settings.md @@ -26,16 +26,16 @@ * `authentication_methods`: object in which each key-value pair in the object indicates whether the authentication method is enabled on this server. * `zulip_version`: the version of Zulip running in the server. -* `zulip_feature_level`: an integer indicatating what features are +* `zulip_feature_level`: 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 mobile apps to decide whether the server supports a given - feature or API change. + for client apps to decide whether the server supports a given + feature or API change. See the [changelog](/api/changelog) for + details on what each feature level means. **Changes**. New in Zulip 2.2. We recommend using an implied value of 0 for Zulip servers that do not send this field. - * `push_notifications_enabled`: whether mobile/push notifications are enabled. * `is_incompatible`: whether the Zulip client that has sent a request to this endpoint is deemed incompatible with the server. diff --git a/templates/zerver/api/sidebar_index.md b/templates/zerver/api/sidebar_index.md index 8df285a8d4..6a89ff2856 100644 --- a/templates/zerver/api/sidebar_index.md +++ b/templates/zerver/api/sidebar_index.md @@ -20,5 +20,6 @@ * [Configuring the Python bindings](/api/configuring-python-bindings) * [Error handling](/api/rest-error-handling) * [Client Libraries](/api/client-libraries) +* [Changelog](/api/changelog) {!rest-endpoints.md!} diff --git a/version.py b/version.py index a78776adbc..e23788000c 100644 --- a/version.py +++ b/version.py @@ -27,9 +27,9 @@ DESKTOP_WARNING_VERSION = "5.0.0" # as we notice; clients using API_FEATURE_LEVEL will just not # use the new feature/API until the bump. # -# Changes should be accompanied by documentation explaining what the new -# level means in templates/zerver/api/server-settings.md. -API_FEATURE_LEVEL = 1 +# Changes should be accompanied by documentation explaining what the +# new level means in templates/zerver/api/changelog.md. +API_FEATURE_LEVEL = 2 # Bump the minor PROVISION_VERSION to indicate that folks should provision # only when going from an old version of the code to a newer version. Bump diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 7e14ecbc4f..aba3d758a3 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -373,7 +373,7 @@ paths: 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 2.2. The + **Changes**: String values are new in Zulip 2.2 (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. @@ -588,7 +588,7 @@ paths: private messages, either a list containing integer user IDs or a list containing string email addresses. - **Changes**: Support using user/stream IDs was added in Zulip 2.0.0. + **Changes**: Support for using user/stream IDs was added in Zulip 2.0.0. schema: type: string example: [9, 10] @@ -1940,8 +1940,8 @@ paths: * 2 => Only administrators can post. * 3 => Only new members can post. - **Changes**: New in Zulip 2.2, replacing the previous is_announcement_only - boolean. + **Changes**: New in Zulip 2.2 (feature level 1), replacing + the previous is_announcement_only boolean. schema: type: integer default: 1 @@ -2506,7 +2506,7 @@ paths: Setting this to `true` will make presence dictionaries be keyed by user_id instead of email. - **Changes**: New in Zulip 2.2. + **Changes**: New in Zulip 2.2 (Unstable with no feature level yet). schema: type: boolean default: false @@ -2631,9 +2631,12 @@ paths: external_authentication_methods: type: array description: | - List of dictionaries describing which external authentication methods - are enabled and their parameters - most importantly the login url, + List of dictionaries describing which external + authentication methods are enabled and their + parameters - most importantly the login url, display_name and display_icon. + + **Changes**: New in Zulip 2.1. items: type: object zulip_version: @@ -3147,7 +3150,8 @@ paths: description: | Whether the stream is limited to announcements. - **Changes**: Deprecated in Zulip 2.2, use `stream_post_policy` instead. + **Changes**: Deprecated in Zulip 2.2 (feature level 1), use + `stream_post_policy` instead. schema: type: boolean example: true @@ -3161,8 +3165,8 @@ paths: * 2 => Only administrators can post. * 3 => Only new members can post. - **Changes**: New in Zulip 2.2, replacing the previous `is_announcement_only` - boolean. + **Changes**: New in Zulip 2.2 (feature level 1), replacing + the previous `is_announcement_only` boolean. schema: type: integer example: 2