From 5802f7775f5e3fcc0749b315c19c2a326d260f97 Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Thu, 18 May 2023 19:11:18 +0200 Subject: [PATCH] api-changelog: Update and clarify docs for feature level 178 entry. Updates the descriptions and examples for there only being two key values: "website" and "aggregated". Also, clarifies that email keys are the Zulip display email. And removes any descriptive text that says presence objects have information about the clients the user is logged into. --- api_docs/changelog.md | 13 +++-- zerver/openapi/zulip.yaml | 102 ++++++++++++++++++++------------------ 2 files changed, 61 insertions(+), 54 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index daa9edcb94..5c29b3279d 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -55,11 +55,14 @@ format used by the Zulip server that they are interacting with. **Feature level 178** -* `POST users/me/presence`, [`POST /register`](/api/register-queue), - [`GET /events`](/api/get-events), `GET /realm/presence`, `GET - /users//presence`: The server no longer stores - which client submitted presence data, and presence responses from - the server will always contain the `aggregated` and `website` keys. +* `POST users/me/presence`, + [`GET /users//presence`](/api/get-user-presence), + [`GET /realm/presence`](/api/get-presence), + [`POST /register`](/api/register-queue), + [`GET /events`](/api/get-events): + The server no longer stores which client submitted presence data, + and presence responses from the server will always contain the + `"aggregated"` and `"website"` keys. **Feature level 177** diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index d46b39db65..3526e50531 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -1049,7 +1049,7 @@ paths: email: type: string description: | - The email of the user. + The Zulip display email of the user. **Deprecated**: This field will be removed in a future release as it is redundant with the `user_id`. @@ -1067,19 +1067,24 @@ paths: type: object description: | `{client_name}`: Object containing the details of the user's - presence on a particular platform. The object key is the client's - platform name, for example `website` or `ZulipDesktop`. + presence. **Changes**: Starting with Zulip 7.0 (feature level 178), this - will always contain two keys, `website` and `aggregated`, with - identical data. The server no longer stores which client submitted - presence updates. + will always be `"website"` as the server no longer stores which + client submitted presence updates. + + Previously, the object key was the client's platform name, for + example `website` or `ZulipDesktop`. additionalProperties: false properties: client: type: string description: | The client's platform name. + + **Changes**: Starting with Zulip 7.0 (feature level 178), this + will always be `"website"` as the server no longer stores which + client submitted presence updates. status: type: string enum: @@ -1098,6 +1103,10 @@ paths: description: | Whether the client is capable of showing mobile/push notifications to the user. + + **Changes**: Starting with Zulip 7.0 (feature level 178), this + will always be `false` as the server no longer stores which + client submitted presence updates. additionalProperties: false example: { @@ -1107,9 +1116,9 @@ paths: "server_timestamp": 1594825445.320078373, "presence": { - "ZulipAndroid/1.0": + "website": { - "client": "ZulipAndroid/1.0", + "client": "website", "status": "idle", "timestamp": 1594825445, "pushable": false, @@ -7523,8 +7532,7 @@ paths: presence: type: object description: | - An object containing the presence details for every client the user has - logged into. + An object containing the presence details for the user. additionalProperties: type: object additionalProperties: false @@ -7540,31 +7548,24 @@ paths: Whether the user had recently interacted with Zulip at the time of the timestamp. - Will be either `active` or `idle` + Will be either `"active"` or `"idle"` description: | - `{client_name}` or `aggregated`: Object containing the details of the user's - presence on a particular platform. + `{client_name}` or `"aggregated"`: Object containing the details of the user's + presence. - Generally, the keys for these objects are the names of the different clients - where this user is logged in, for example `website` or `ZulipDesktop`. + **Changes**: Starting with Zulip 7.0 (feature level 178), this will always + contain two keys, `"website"` and `"aggregated"`, with identical data. The + server no longer stores which client submitted presence updates. - There is also an `aggregated` key, which matches the contents of the object - that has been updated most recently. - - For most applications, you'll just want to look at the `aggregated` key. - - **Changes**: Starting with Zulip 7.0 (feature level 178), this - will always contain two keys, `website` and `aggregated`, with - identical data. The server no longer stores which client submitted - presence updates. + Previously, the `{client_name}` keys for these objects were the names of the + different clients where the user was logged in, for example `website` or + `ZulipDesktop`. example: { "presence": { "website": {"timestamp": 1532697622, "status": "active"}, - "ZulipMobile": - {"timestamp": 1522687421, "status": "active"}, "aggregated": {"timestamp": 1532697622, "status": "active"}, }, @@ -9054,9 +9055,8 @@ paths: additionalProperties: type: object description: | - `{user_email}`: Object containing the details of a user's presence - on every client the user is logged into. The object's key is the - user's email. + `{user_email}`: Object containing the details of a user's presence. + The object's key is the user's Zulip display email. additionalProperties: $ref: "#/components/schemas/Presence" example: @@ -9066,16 +9066,16 @@ paths: { "iago@zulip.com": { - "ZulipPython": + "website": { - "client": "ZulipPython", + "client": "website", "pushable": false, "status": "active", "timestamp": 1656958485, }, "aggregated": { - "client": "ZulipPython", + "client": "website", "status": "active", "timestamp": 1656958485, }, @@ -10941,8 +10941,8 @@ paths: type: object description: | `{user_id}` or `{user_email}`: Object containing the details of a user's - presence on every client the user is logged into. Depending on the value - of `slim_presence`, the object's key is either the user's ID or email. + presence . Depending on the value of `slim_presence`, the object's key is + either the user's ID or the user's Zulip display email. additionalProperties: $ref: "#/components/schemas/Presence" server_timestamp: @@ -17518,34 +17518,34 @@ components: Presence: type: object description: | - `{client_name}` or `aggregated`: Object containing the details of the user's - presence on a particular platform. + `{client_name}` or `"aggregated"`: Object containing the details of the user's + presence. - Generally, the keys for these objects are the names of the different clients - where this user is logged in, for example `website` or `ZulipDesktop`. + **Changes**: Starting with Zulip 7.0 (feature level 178), this will always + contain two keys, `"website"` and `"aggregated"`, with identical data. The + server no longer stores which client submitted presence updates. - There is also an `aggregated` key, which matches the contents of the object - that has been updated most recently (except for the `pushable` value which is - not present). - - **Changes**: Starting with Zulip 7.0 (feature level 178), this - will always contain two keys, `website` and `aggregated`, with - identical data. The server no longer stores which client submitted - presence updates. + Previously, the `{client_name}` keys for these objects were the names of the + different clients where the user was logged in, for example `website` or + `ZulipDesktop`. additionalProperties: false properties: client: type: string description: | The client's platform name. + + **Changes**: Starting with Zulip 7.0 (feature level 178), this will + always be `"website"` as the server no longer stores which client + submitted presence data. status: type: string enum: - idle - active description: | - The status of the user on this client. Will be either `idle` - or `active`. + The status of the user on this client. Will be either `"idle"` + or `"active"`. timestamp: type: integer description: | @@ -17557,7 +17557,11 @@ components: Whether the client is capable of showing mobile/push notifications to the user. - Not present in objects with the `aggregated` key. + Not present in objects with the `"aggregated"` key. + + **Changes**: Starting with Zulip 7.0 (feature level 178), always + `false` when present as the server no longer stores which client + submitted presence data. Draft: type: object description: |