Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Tim Abbott 2020-04-28 20:55:42 -07:00
parent f1ec02b40a
commit cbe0723199
7 changed files with 153 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
templates/zerver/api/changelog.md Normal file
View File

@ -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.

9
templates/zerver/api/get-all-users.md
View File

@ -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.

16
templates/zerver/api/get-messages.md
View File

@ -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.

8
templates/zerver/api/server-settings.md
View File

@ -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.

1
templates/zerver/api/sidebar_index.md
View File

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

6
version.py
View File

@ -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

24
zerver/openapi/zulip.yaml
View File

@ -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