paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-30 19:43:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

api_docs: Document "/users/me/presence" endpoint.

Browse Source 
Co-authored-by: Tim Abbott <tabbott@zulip.com>
Co-authored-by: Mateusz Mandera <mateusz.mandera@zulip.com>
This commit is contained in:
Vector73
2024-06-07 14:19:36 +05:30
committed by Tim Abbott
parent f0ec4f5732
commit d60150d39d
5 changed files with 257 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
api_docs/changelog.md
View File

@@ -22,8 +22,8 @@ format used by the Zulip server that they are interacting with.
**Feature level 263**:
* `POST /users/me/presence`: A new `last_update_id`
parameter can be given, instructing
* [`POST /users/me/presence`](/api/update-presence):
A new `last_update_id` parameter can be given, instructing
the server to only fetch presence data with `last_update_id`
greater than the value provided. The server also provides
a `presence_last_update_id` field in the response, which
@@ -38,10 +38,10 @@ format used by the Zulip server that they are interacting with.
* [`POST /register`](/api/register-queue): The response now also
includes a `presence_last_update_id` field, with the same
meaning as described above for `/users/me/presence`.
meaning as described above for [`/users/me/presence`](/api/update-presence).
In the same way, the retrieved value can be passed when
querying `/users/me/presence` to avoid re-fetching of already
known data.
querying [`/users/me/presence`](/api/update-presence) to avoid
re-fetching of already known data.
**Feature level 262**:
@@ -798,7 +798,7 @@ No changes; feature level used for Zulip 7.0 release.
**Feature level 178**
* `POST /users/me/presence`,
* [`POST /users/me/presence`](/api/update-presence),
[`GET /users/<user_id_or_email>/presence`](/api/get-user-presence),
[`GET /realm/presence`](/api/get-presence),
[`POST /register`](/api/register-queue),

1
api_docs/include/rest-endpoints.md
View File

@@ -71,6 +71,7 @@
* [Get user presence](/api/get-user-presence)
* [Get a user's status](/api/get-user-status)
* [Get presence of all users](/api/get-presence)
* [Update your presence](/api/update-presence)
* [Get attachments](/api/get-attachments)
* [Delete an attachment](/api/remove-attachment)
* [Update settings](/api/update-settings)

6
zerver/openapi/python_examples.py
View File

@@ -238,14 +238,18 @@ def get_user_status(client: Client) -> None:
@openapi_test_function("/users/me/presence:post")
def update_presence(client: Client) -> None:
# This endpoint is not documented yet. So, we are not validating the schema here.
# {code_example|start}
# Update your presence.
request = {
"status": "active",
"ping_only": False,
"new_user_input": False,
"last_update_id": -1,
}
result = client.update_presence(request)
# {code_example|end}
validate_response_result(result)
validate_against_openapi_schema(result, "/users/me/presence", "post", "200")
@openapi_test_function("/users:post")

248
zerver/openapi/zulip.yaml
View File

@@ -8947,6 +8947,248 @@ paths:
"msg": "",
"alert_words": ["bar", "natural", "illustrious"],
}
/users/me/presence:
post:
operationId: update-presence
summary: Update your presence status and fetch presence data for the realm
tags: ["users"]
description: |
Update your
[presence/availability](https://zulip.com/help/status-and-availability#availability)
status and fetch presence of other users in realm in a bulk.
This is the endpoint meant to be used by clients for both reporting
their presence status to the server and obtaining the presence info
of all other users to build the buddy list by polling it regularly,
in parallel with receiving presence update events via the event system.
Accurate presence is one of the most expensive parts of any team chat application
(in terms of bandwidth and other resources). It's thus important that clients
implementing Zulip's presence system use the modern `last_update_id` protocol to
minimize fetching duplicate presence data.
If the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level
setting is set to `true`, presence information of only accessible
users is included in the response.
See [Zulip's developer documentation][subsystems-presence]
for details on the data model for presence in Zulip.
The Zulip server is responsible for implementing [invisible
mode](https://zulip.com/help/status-and-availability#invisible-mode), which
disables sharing presence data. Nonetheless, clients should check
the `presence_enabled` field in user objects in order to display the current user
as online or offline based on whether they are sharing presence information.
[subsystems-presence]: https://zulip.readthedocs.io/en/latest/subsystems/presence.html
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
last_update_id:
type: integer
description: |
Specifies what presence data the client already has, allowing the
server to only return presence data more recent than that.
This parameter should be set to `-1` during initialization of the
client in order to fetch all data, unless the client is obtaining
initial presence metadata from the [`POST /register` endpoint](/api/register-queue).
Afterwards, its value should be obtained by reading
`presence_last_update_id` from the server's response to the previous
request in order to implement incremental fetches of presence data.
**Changes**: New in Zulip 9.0 (feature level 263). Previously, the
server sent data for all users who had been active in the last two
weeks unconditionally.
example: 5
new_user_input:
description: |
Whether the user has interacted with the client since the previous
presence request from this client, such as moving the mouse or using
the keyboard.
These data are used by the server to support certain [usage
statistics](/help/analytics).
User interface clients that might run in the background without the
user ever interacting with them should be careful to only pass `true`
if the user has actually interacted with the client, to avoid
corrupting usage statistics graphs.
type: boolean
example: false
default: false
ping_only:
type: boolean
description: |
Whether the client is sending a ping-only request, meaning it only
wants to update the user's presence status.
Otherwise, also requests the server to return presence data of all
users in the realm, further affected by the `last_update_id`
parameter.
example: false
default: false
slim_presence:
description: |
Legacy parameter for configuring the format in which the server will
return presence data for the realm. Modern clients should pass
`last_update_id`, which implies the client expects the modern format,
and should not pass this property unless interacting with an older
server.
Legacy clients that do not yet support `last_update_id` may use the
value of `true` to request the modern format. The legacy format, sent
when `slim_presence` is `false`, will be removed entirely in a future
release.
**Changes**: **Deprecated** in Zulip 9.0 (feature level 263);
using the modern `last_update_id` API is the recommended way to
request the modern format.
New in Zulip 3.0 (Unstable with no feature level yet).
type: boolean
example: false
default: false
deprecated: true
status:
type: string
enum:
- idle
- active
description: |
The status of the user on this client. Will be either `"idle"`
or `"active"`.
Clients should report the user as active on this device if the client
knows that the user is presently using the device (and thus would
potentially see a desktop notification immediately), even if the user
has not directly interacted with the Zulip client.
Otherwise, it should report the user as idle.
See the related `new_user_input` parameter for how a client should
report whether the user is actively using the Zulip client.
example: active
required:
- status
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
required:
- result
- msg
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
presence_last_update_id:
type: integer
description: |
Provides the `last_update_id` value of the latest presence data
fetched by the server and included in the response in
`presences`. This allows the client to have an identifier number
up to which it knows it has obtained all the presence data.
The client should then pass this value when next queries this
endpoint, in order to only receive newer presence data to avoid
redundant fetching of already known information.
**Changes**: New in Zulip 9.0 (feature level 263).
server_timestamp:
type: number
description: |
The time when the server fetched the `presences` data included
in the response.
Only present if `ping_only` is `false`.
zephyr_mirror_active:
type: boolean
deprecated: true
description: |
Legacy property for a part of the Zephyr mirroring system.
**Deprecated**. Clients should ignore this field.
presences:
type: object
description: |
A dictionary where each entry describes the presence details
of a user in the Zulip organization.
Only present if `ping_only` is `false`.
additionalProperties:
description: |
A map from `{user_id}` (modern) or `{user_email}` (legacy)
properties to objects containing the presence data for that
user.
Depending on the value of `slim_presence`, the object's key is
either the user's ID or the user's Zulip API email. If
`slim_presence` is `true`, the presence information is fetched
in the modern API format which includes `active_timestamp` and
`idle_timestamp` of the user.
**Note**: The old legacy format should only be used when
interacting with old servers. It will be removed as soon as
doing so is practical.
oneOf:
- type: object
additionalProperties:
$ref: "#/components/schemas/Presence"
- type: object
additionalProperties: false
properties:
active_timestamp:
type: integer
description: |
The UNIX timestamp of the last time a client connected
to Zulip reported that the user was actually present
(e.g. via focusing a browser window or interacting
with a computer running the desktop app).
Clients should display users with a current
`active_timestamp` as fully present.
idle_timestamp:
type: integer
description: |
The UNIX timestamp of the last time the user had a
client connected to Zulip, including idle clients
where the user hasn't interacted with the system
recently.
The Zulip server has no way of distinguishing whether
an idle web app user is at their computer, but hasn't
interacted with the Zulip tab recently, or simply left
their desktop computer on when they left.
Thus, clients should display users with a current
`idle_timestamp` but no current `active_timestamp` as
potentially present.
example:
{
"msg": "",
"presences":
{
"10":
{
"idle_timestamp": 1656958530,
"active_timestamp": 1656958520,
},
},
"result": "success",
"server_timestamp": 1656958539.6287155,
"presence_last_update_id": 1000,
}
/users/me/status:
post:
operationId: update-status
@@ -13164,9 +13406,9 @@ paths:
Provides the `last_update_id` value of the latest presence data fetched by
the server and included in the response in `presences`. This can be used
as the value of the `presence_last_update_id` parameter when polling
for presence data at the /users/me/presence endpoint to tell the server
to only fetch the relevant newer data in order to skip redundant
already-known presence information.
for presence data at the [/users/me/presence](/api/update-presence) endpoint
to tell the server to only fetch the relevant newer data in order to skip
redundant already-known presence information.
**Changes**: New in Zulip 9.0 (feature level 263).

1
zerver/tests/test_openapi.py
View File

@@ -220,7 +220,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
checked_endpoints: Set[str] = set()
pending_endpoints = {
#### TODO: These endpoints are a priority to document:
"/users/me/presence",
# These are a priority to document but don't match our normal URL schemes
# and thus may be complicated to document with our current tooling.
# (No /api/v1/ or /json prefix).