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

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.
This commit is contained in:
Lauryn Menard 2023-05-18 19:11:18 +02:00 committed by Tim Abbott
parent 1184bdc934
commit 5802f7775f
2 changed files with 61 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
api_docs/changelog.md
View File

@ -55,11 +55,14 @@ format used by the Zulip server that they are interacting with.
**Feature level 178** **Feature level 178**
* `POST users/me/presence`, [`POST /register`](/api/register-queue), * `POST users/me/presence`,
[`GET /events`](/api/get-events), `GET /realm/presence`, `GET [`GET /users/<user_id_or_email>/presence`](/api/get-user-presence),
/users/<user_id_or_email>/presence`: The server no longer stores [`GET /realm/presence`](/api/get-presence),
which client submitted presence data, and presence responses from [`POST /register`](/api/register-queue),
the server will always contain the `aggregated` and `website` keys. [`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** **Feature level 177**

102
zerver/openapi/zulip.yaml
View File

@ -1049,7 +1049,7 @@ paths:
email: email:
type: string type: string
description: | description: |
The email of the user. The Zulip display email of the user.
**Deprecated**: This field will be removed in a future **Deprecated**: This field will be removed in a future
release as it is redundant with the `user_id`. release as it is redundant with the `user_id`.
@ -1067,19 +1067,24 @@ paths:
type: object type: object
description: | description: |
`{client_name}`: Object containing the details of the user's `{client_name}`: Object containing the details of the user's
presence on a particular platform. The object key is the client's presence.
platform name, for example `website` or `ZulipDesktop`.
**Changes**: Starting with Zulip 7.0 (feature level 178), this **Changes**: Starting with Zulip 7.0 (feature level 178), this
will always contain two keys, `website` and `aggregated`, with will always be `"website"` as the server no longer stores which
identical data. The server no longer stores which client submitted client submitted presence updates.
presence updates.
Previously, the object key was the client's platform name, for
example `website` or `ZulipDesktop`.
additionalProperties: false additionalProperties: false
properties: properties:
client: client:
type: string type: string
description: | description: |
The client's platform name. 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: status:
type: string type: string
enum: enum:
@ -1098,6 +1103,10 @@ paths:
description: | description: |
Whether the client is capable of showing mobile/push notifications Whether the client is capable of showing mobile/push notifications
to the user. 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 additionalProperties: false
example: example:
{ {
@ -1107,9 +1116,9 @@ paths:
"server_timestamp": 1594825445.320078373, "server_timestamp": 1594825445.320078373,
"presence": "presence":
{ {
"ZulipAndroid/1.0": "website":
{ {
"client": "ZulipAndroid/1.0", "client": "website",
"status": "idle", "status": "idle",
"timestamp": 1594825445, "timestamp": 1594825445,
"pushable": false, "pushable": false,
@ -7523,8 +7532,7 @@ paths:
presence: presence:
type: object type: object
description: | description: |
An object containing the presence details for every client the user has An object containing the presence details for the user.
logged into.
additionalProperties: additionalProperties:
type: object type: object
additionalProperties: false additionalProperties: false
@ -7540,31 +7548,24 @@ paths:
Whether the user had recently interacted with Zulip at the time Whether the user had recently interacted with Zulip at the time
of the timestamp. of the timestamp.
Will be either `active` or `idle` Will be either `"active"` or `"idle"`
description: | description: |
`{client_name}` or `aggregated`: Object containing the details of the user's `{client_name}` or `"aggregated"`: Object containing the details of the user's
presence on a particular platform. presence.
Generally, the keys for these objects are the names of the different clients **Changes**: Starting with Zulip 7.0 (feature level 178), this will always
where this user is logged in, for example `website` or `ZulipDesktop`. 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 Previously, the `{client_name}` keys for these objects were the names of the
that has been updated most recently. different clients where the user was logged in, for example `website` or
`ZulipDesktop`.
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.
example: example:
{ {
"presence": "presence":
{ {
"website": "website":
{"timestamp": 1532697622, "status": "active"}, {"timestamp": 1532697622, "status": "active"},
"ZulipMobile":
{"timestamp": 1522687421, "status": "active"},
"aggregated": "aggregated":
{"timestamp": 1532697622, "status": "active"}, {"timestamp": 1532697622, "status": "active"},
}, },
@ -9054,9 +9055,8 @@ paths:
additionalProperties: additionalProperties:
type: object type: object
description: | description: |
`{user_email}`: Object containing the details of a user's presence `{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 The object's key is the user's Zulip display email.
user's email.
additionalProperties: additionalProperties:
$ref: "#/components/schemas/Presence" $ref: "#/components/schemas/Presence"
example: example:
@ -9066,16 +9066,16 @@ paths:
{ {
"iago@zulip.com": "iago@zulip.com":
{ {
"ZulipPython": "website":
{ {
"client": "ZulipPython", "client": "website",
"pushable": false, "pushable": false,
"status": "active", "status": "active",
"timestamp": 1656958485, "timestamp": 1656958485,
}, },
"aggregated": "aggregated":
{ {
"client": "ZulipPython", "client": "website",
"status": "active", "status": "active",
"timestamp": 1656958485, "timestamp": 1656958485,
}, },
@ -10941,8 +10941,8 @@ paths:
type: object type: object
description: | description: |
`{user_id}` or `{user_email}`: Object containing the details of a user's `{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 presence . Depending on the value of `slim_presence`, the object's key is
of `slim_presence`, the object's key is either the user's ID or email. either the user's ID or the user's Zulip display email.
additionalProperties: additionalProperties:
$ref: "#/components/schemas/Presence" $ref: "#/components/schemas/Presence"
server_timestamp: server_timestamp:
@ -17518,34 +17518,34 @@ components:
Presence: Presence:
type: object type: object
description: | description: |
`{client_name}` or `aggregated`: Object containing the details of the user's `{client_name}` or `"aggregated"`: Object containing the details of the user's
presence on a particular platform. presence.
Generally, the keys for these objects are the names of the different clients **Changes**: Starting with Zulip 7.0 (feature level 178), this will always
where this user is logged in, for example `website` or `ZulipDesktop`. 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 Previously, the `{client_name}` keys for these objects were the names of the
that has been updated most recently (except for the `pushable` value which is different clients where the user was logged in, for example `website` or
not present). `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.
additionalProperties: false additionalProperties: false
properties: properties:
client: client:
type: string type: string
description: | description: |
The client's platform name. 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: status:
type: string type: string
enum: enum:
- idle - idle
- active - active
description: | description: |
The status of the user on this client. Will be either `idle` The status of the user on this client. Will be either `"idle"`
or `active`. or `"active"`.
timestamp: timestamp:
type: integer type: integer
description: | description: |
@ -17557,7 +17557,11 @@ components:
Whether the client is capable of showing mobile/push notifications Whether the client is capable of showing mobile/push notifications
to the user. 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: Draft:
type: object type: object
description: | description: |