Audit of API docs changes notes against central changelog (feature levels 1-27)

[laurynmm]

Unless otherwise noted, each entry just needs Changes note(s) added to API documentation:

Feature level 1:

• POST /register: Added zulip_feature_level to the response if zulip_version is among the requested event_types.
• 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.

Feature level 3:

• zulip_version and zulip_feature_level are always returned in POST /register; previously they were only returned if event_types included zulip_version.
• Added new presence_enabled user notification setting; previously presence was always enabled.

Feature level 4:

• jitsi_server_url, development_environment, server_generation, password_min_length, password_min_guesses, max_file_upload_size_mib, max_avatar_file_size_mib, server_inline_image_preview, server_inline_url_embed_preview, server_avatar_changes_disabled and server_name_changes_disabled fields are now available via POST /register to make them accessible to all the clients; they were only internally available to Zulip's web app prior to this.

Feature level 5:

• GET /events: realm_bot events, sent when changes are made to bot users, now contain an integer-format owner_id field, replacing the owner field (which was an email address).

Feature 6:

• GET /events: realm_user events to update a user's avatar now include the avatar_version field, which is important for correctly refetching medium-size avatar images when the user's avatar changes.
• GET /users, GET /users/{user_id}: User objects now contain the avatar_version field as well.

Feature 7:

• GET /events: realm_user and realm_bot events no longer contain an email field to identify the user; use the user_id field instead. Previously, some (but not all) events of these types contained an email key in addition to to user_id) for identifying the modified user.
• GET /events: realm_user events sent when a user's role changes now include role property, instead of the previous is_guest or is_admin booleans.

Documented as feature level 8, but listed in changelog as feature level 7

• PATCH /users/{user_id}: The is_admin and is_guest parameters were removed in favor of the more general role parameter for specifying a change in user role.

Feature level 10:

• GET users/me: Removed client_id and short_name from the response to this endpoint. These fields had no purpose and were inconsistent with other API responses describing users.

Feature level 11:

• POST /register: The response now contains a is_owner, similar to the existing is_admin and is_guest fields.

Inconsistent or incomplete: Added to GET /events as well and null information not documented:
- [ ] POST /register: Added realm_community_topic_editing_limit_seconds to the response, the time limit before community topic editing is forbidden. A null value means no limit. This was previously hard-coded in the server as 86400 seconds (1 day). This was incorrectly documented in GET /events and has since been removed from that endpoint's documentation. And has been removed from the POST /register response as well.

Documented as feature level 11 but listed in changelog as feature level 12

• GET users/{user_id}/subscriptions/{stream_id}:
  New endpoint added for checking if another user is subscribed to a stream.

Feature level 13:

• GET /events: delete_message events have new behavior. The sender and sender_id fields were removed, and the message_id field was replaced by a message_ids list for clients with the bulk_message_deletion client capability. All clients should upgrade; we expect bulk_message_deletion to be required in the future.

Feature level 14:

• GET users/me/subscriptions: Removed the is_old_stream field from Stream objects. This field was always equivalent to stream_weekly_traffic != null on the same object.

Feature level 16: Question: unlike other parameters / return values that have been removed from endpoints, this was removed as a whole concept from Zulip. So do we want a Change note for this in the main endpoint description?

• GET /users/me: Removed pointer from the response, as the "pointer" concept is being removed in Zulip.

Feature level 19:

• GET /events: subscriptions event with op="peer_add" and op="peer_remove" now identify the modified stream by a stream_id field, replacing the old name field.

Feature level 21: NOTE: would document on the PATCH /settings endpoint

• PATCH /settings/display: Replaced the night_mode boolean with color_scheme as part of supporting automatic night theme detection.

Feature level 26:

• The sender_short_name field is no longer included in GET /messages.
• The short_name field is removed from display_recipients in GET /messages.

Feature level 27:

• The short_name field is removed from display_recipients in POST /users.

[gnprice]

Excellent! Looking forward to these fixes.

Skimming a few of these, one thing I notice is that some of them are missing links from the changelog to the endpoint that changed. For example several of the entries you have for feature level 1; and one at FL 2 and one at 22 and a few in between. Those would be nice to fix too; in some cases, like "Added None as a video call provider option.", it's actually not easy to be sure exactly what is said to have changed.

The changelog also has a misformatting at FL 5 that's probably a tiny fix but is kind of confusing as rendered:

Question: unlike other parameters / return values that have been removed from endpoints, this was removed as a whole concept from Zulip. So do we want a Change note for this in the main endpoint description?

• [ ] GET /users/me: Removed pointer from the response, as the "pointer" concept is being removed in Zulip.

Yeah, I'd imagine documenting this in much the same format as any other removed response property.

[zulipbot]

@laurynmm You have been unassigned from this issue because you have not made any updates for over 14 days. Please feel free to reclaim the issue if you decide to pick up again. Thanks!

[zulipbot]

Hello @zulip/server-api members, this issue was labeled with the "area: documentation (api and integrations)" label, so you may want to check it out!