api docs: Add an API changelog page.

I imagine this can be improved in various ways, but I've initialized
this with all the **Changes** entries recorded in either zulip.yaml or
the rest of the API documentation, and I expect we'll be able to
iterate on this effectively.

It'll also be useful as a record of changes that we should remember to
document the API documentation as we document more endpoints that
currently don't discuss these issues.

While working on this, I fixed various issues where feature levels
could be mentioned or endpoints didn't properly document changes.

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.

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`
+    * `bot_owner_id`: If the user is a bot (i.e. `is_bot` is `True`),
-      is the user ID of the bot's owner (usually, whoever created the bot).
+      `bot_owner` is the user ID of the bot's owner (usually, whoever
-      **Changes**: New in Zulip 2.2.  In previous versions, there was a `bot_owner`
+      created the bot).  **Changes**: New in Zulip 2.2 (feature level
-      field containing the email address of the bot's owner.
+      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.

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
+           **Changes**: New in Zulip 2.2 (feature level 2). The `user`
-           deprecated and will be removed in the future.
+           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
+      line (these are generated by [custom linkification
-      [custom linkification filters][linkification-filters] that match
+      filters][linkification-filters] that match content in the
-      content in the message's topic.)  **Changes**: Before Zulip 2.2,
+      message's topic.)  **Changes**: New in Zulip 2.2 (feature level
-      this field was called `subject_links`; clients are recommended
+      1).  Previously, this field was called `subject_links`; clients
-      to rename `subject_links` to `topic_links` if present for
+      are recommended to rename `subject_links` to `topic_links` if
-      compatibility with older Zulip servers.
+      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.

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
+    for client apps to decide whether the server supports a given
-    feature or API change.
+    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.

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!}

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
+# Changes should be accompanied by documentation explaining what the
-# level means in templates/zerver/api/server-settings.md.
+# new level means in templates/zerver/api/changelog.md.
-API_FEATURE_LEVEL = 1
+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

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
+          **Changes**: New in Zulip 2.2 (feature level 1), replacing
-          boolean.
+          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
+                        List of dictionaries describing which external
-                        are enabled and their parameters - most importantly the login url,
+                        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`
+          **Changes**: New in Zulip 2.2 (feature level 1), replacing
-          boolean.
+          the previous `is_announcement_only` boolean.
         schema:
           type: integer
         example: 2