api: Document /realm/presence API endpoint.

zulip · Jul 18, 2022 · e96892c · e96892c
1 parent acecbcb
commit e96892c
Show file tree

Hide file tree

Showing 4 changed files with 82 additions and 1 deletion.
diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md
@@ -54,6 +54,7 @@
 * [Deactivate own user](/api/deactivate-own-user)
 * [Set "typing" status](/api/set-typing-status)
 * [Get user presence](/api/get-user-presence)
+* [Get presence of all the users](/api/get-presence)
 * [Get attachments](/api/get-attachments)
 * [Delete an attachment](/api/remove-attachment)
 * [Update settings](/api/update-settings)

diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.py
@@ -140,6 +140,16 @@ def test_authorization_errors_fatal(client: Client, nonadmin_client: Client) ->
     validate_against_openapi_schema(result, "/users/me/subscriptions", "post", "400")
 
 
+@openapi_test_function("/realm/presence:get")
+def get_presence(client: Client) -> None:
+
+    # {code_example|start}
+    # Get presence information of all the users in an organization.
+    result = client.get_realm_presence()
+    # {code_example|end}
+    validate_against_openapi_schema(result, "/realm/presence", "get", "200")
+
+
 @openapi_test_function("/users/{user_id_or_email}/presence:get")
 def get_user_presence(client: Client) -> None:
 
@@ -1485,6 +1495,7 @@ def test_users(client: Client, owner_client: Client) -> None:
     set_typing_status(client)
     update_presence(client)
     get_user_presence(client)
+    get_presence(client)
     create_user_group(client)
     user_group_id = get_user_groups(client)
     update_user_group(client, user_group_id)

diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
@@ -7679,6 +7679,76 @@ paths:
                               },
                           },
                       }
+  /realm/presence:
+    get:
+      operationId: get-presence
+      summary: Get presence of all the users
+      tags: ["server_and_organizations"]
+      description: |
+        Get the presence information of all the users in an organization.
+
+        `GET {{ api_url }}/v1/realm/presence`
+
+        See
+        [Zulip's developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/presence.html)
+        for details on the data model for presence in Zulip.
+      responses:
+        "200":
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/JsonSuccessBase"
+                  - $ref: "#/components/schemas/SuccessDescription"
+                  - additionalProperties: false
+                    properties:
+                      result: {}
+                      msg: {}
+                      server_timestamp:
+                        type: number
+                        description: |
+                          The time when the server fetched the `presences` data included
+                          in the response.
+                      presences:
+                        type: object
+                        description: |
+                          An object that contains `presence` objects for all the users,
+                          each identified by user email as the key.
+                        additionalProperties:
+                          type: object
+                          description: |
+                            `{user_email}`: Object containing details of a user's presence
+                            on every client the user is logged into. The keys for these
+                            objects are the emails of the different users whose presence
+                            data is included.
+                          additionalProperties:
+                            $ref: "#/components/schemas/Presence"
+                    example:
+                      {
+                        "msg": "",
+                        "presences":
+                          {
+                            "iago@zulip.com":
+                              {
+                                "ZulipPython":
+                                  {
+                                    "client": "ZulipPython",
+                                    "pushable": false,
+                                    "status": "active",
+                                    "timestamp": 1656958485,
+                                  },
+                                "aggregated":
+                                  {
+                                    "client": "ZulipPython",
+                                    "status": "active",
+                                    "timestamp": 1656958485,
+                                  },
+                              },
+                          },
+                        "result": "success",
+                        "server_timestamp": 1656958539.6287155,
+                      }
   /realm/profile_fields:
     get:
       operationId: get-custom-profile-fields

diff --git a/zerver/tests/test_openapi.py b/zerver/tests/test_openapi.py
@@ -205,7 +205,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
     checked_endpoints: Set[str] = set()
     pending_endpoints = {
         #### TODO: These endpoints are a priority to document:
-        "/realm/presence",
         "/users/me/presence",
         "/users/me/alert_words",
         # These are a priority to document but don't match our normal URL schemes