From bb735460e5c1baa9d715a995ea81ff338ea66572 Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Fri, 26 May 2023 17:03:39 +0200 Subject: [PATCH] api-docs: Update avatar_url descriptions for feature level 163 change. Updates the descriptions of the `avatar_url` field in message and user objects to be clear that the current user must have access to the other user's real email address in order for the value to ever be `null`. Also adds a bullet point to the API changelog feature level 163 entry about this change. --- api_docs/changelog.md | 8 ++++++++ zerver/openapi/zulip.yaml | 31 +++++++++++++++++++++++-------- 2 files changed, 31 insertions(+), 8 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index ccbbd1ce74..c770c37e2f 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -213,6 +213,14 @@ format used by the Zulip server that they are interacting with. * [`GET /events`](/api/get-events): Event for updating a user's `delivery_email` is now sent to all users who have access to it, and is also sent when a user's `email_address_visibility` setting changes. +* [`GET /events`](/api/get-events), [`POST /register`](/api/register-queue) + [`GET /users`](/api/get-users), [`GET /users/{user_id}`](/api/get-user), + [`GET /users/{email}`](/api/get-user-by-email), + [`GET /users/me`](/api/get-own-user), [`GET /messages`](/api/get-messages), + [`GET /messages/{message_id}`](/api/get-message): Whether the `avatar_url` + field in message and user objects returned by these endpoints can be `null` + now depends on if the current user has access to the other user's real + email address based on the other user's `email_address_visibility` policy. * [`POST /register`](/api/register-queue), [`PATCH /settings`](/api/update-settings), [`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults): Added user setting `email_address_visibility`, to replace the diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 92ff83c520..7fceaacd92 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -17402,10 +17402,18 @@ components: type: string nullable: true description: | - The URL of the user's avatar. Can be `null` only if client_gravatar was passed, - which means that the user has not uploaded an avatar in Zulip, and the - client should compute the gravatar URL by hashing the - user's Zulip API email address itself for this user. + The URL of the message sender's avatar. Can be `null` only if + the current user has access to the sender's real email address + and `client_gravatar` was `true`. + + If `null`, then the sender has not uploaded an avatar in Zulip, + and the client can compute the gravatar URL by hashing the + sender's email address, which corresponds in this case to their + real email address. + + **Changes**: Before Zulip 7.0 (feature level 163), access to a + user's real email address was a realm-level setting. As of this + feature level, `email_address_visibility` is a user setting. client: type: string description: | @@ -17970,11 +17978,18 @@ components: type: string nullable: true description: | - URL for the user's avatar. Will be `null` if the `client_gravatar` - query parameter was set to `true` and the user's avatar is hosted by - the Gravatar provider (i.e. the user has never uploaded an avatar). + URL for the user's avatar. - **Changes**: In Zulip 3.0 (feature level 18), if the client has the + Will be `null` if the `client_gravatar` + query parameter was set to `true`, the current user has access to + this user's real email address, and this user's avatar is hosted by + the Gravatar provider (i.e. this user has never uploaded an avatar). + + **Changes**: Before Zulip 7.0 (feature level 163), access to a + user's real email address was a realm-level setting. As of this + feature level, `email_address_visibility` is a user setting. + + In Zulip 3.0 (feature level 18), if the client has the `user_avatar_url_field_optional` capability, this will be missing at the server's sole discretion. avatar_version: