api docs: Document GET /users/<email>/presence.

Tweaked by tabbott to describe more clearly what this is for.

templates/zerver/api/get-presence.md

@@ -0,0 +1,78 @@
+# Get user presence
+
+Get the presence status for a specific user.
+
+This endpoint is most useful for embedding data about a user's
+presence status in other sites (E.g. an employee directory).  Full
+Zulip clients like mobile/desktop apps will want to use the main
+presence endpoint, which returns data for all active users in the
+organization, instead.
+
+`GET {{ api_url }}/v1/users/<email>/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.
+
+## Usage examples
+
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="python">Python</li>
+<li data-language="curl">curl</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl {{ api_url }}/v1/users/<email>/presence \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+{generate_code_example(python)|/users/{email}/presence:get|example}
+
+</div>
+
+</div>
+
+</div>
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/users/{email}/presence:get}
+
+## Response
+
+#### Return values
+
+* `presence`: An object containing the presence details for every type
+  of client the user has ever logged into.
+    * `<client_name>` or `aggregated`: the keys for these objects are
+      the names of the different clients where this user is logged in,
+      like `website`, `ZulipDesktop`, `ZulipTerminal`, or
+      `ZulipMobile`. 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.
+        * `timestamp`: when this update was received; if the timestamp
+          is more than a few minutes in the past, the user is offline.
+        * `status`: either `active` or `idle`: whether the user had
+          recently interacted with Zulip at the time in the timestamp
+          (this distinguishes orange vs. green dots in the Zulip web
+          UI; orange/idle means we don't know whether the user is
+          actually at their computer or just left the Zulip app open
+          on their desktop).
+        * `pushable`: whether the client accepts push notifications or not.
+        * `client`: the name of the client this presence information refers to.
+          Matches the object's key if this isn't the `aggregated` object.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/users/{email}/presence:get|fixture(200)}

templates/zerver/help/include/rest-endpoints.md

@@ -27,6 +27,7 @@
 * [Get profile](/api/get-profile)
 * [Create a user](/api/create-user)
 * [Set "typing" status](/api/typing)
+* [Get user presence](/api/get-presence)
 
 #### Server & organizations
 

zerver/lib/api_test_helpers.py

@@ -99,6 +99,16 @@ def test_authorization_errors_fatal(client, nonadmin_client):
     validate_against_openapi_schema(result, '/users/me/subscriptions', 'post',
                                     '400_unauthorized_errors_fatal_true')
 
+def get_user_presence(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # Get presence information for "iago@zulip.com"
+    result = client.get_user_presence('iago@zulip.com')
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/users/{email}/presence', 'get', '200')
+
 def create_user(client):
     # type: (Client) -> None
 
@@ -640,6 +650,7 @@ TEST_FUNCTIONS = {
     '/users:post': create_user,
     'get-profile': get_profile,
     'add-subscriptions': add_subscriptions,
+    '/users/{email}/presence:get': get_user_presence,
     '/users/me/subscriptions:delete': remove_subscriptions,
     '/users/me/subscriptions/muted_topics:patch': toggle_mute_topic,
     '/users:get': get_members,
@@ -723,6 +734,7 @@ def test_users(client):
     get_profile(client)
     upload_file(client)
     set_typing_status(client)
+    get_user_presence(client)
 
 def test_streams(client, nonadmin_client):
     # type: (Client, Client) -> None

zerver/openapi/zulip.yaml

@@ -848,6 +848,57 @@ paths:
                         "msg": "Email 'newbie@zulip.com' already in use",
                         "result": "error"
                     }
+  /users/{email}/presence:
+    get:
+      description: Get the presence status for a specific user.
+      parameters:
+      - name: email
+        in: path
+        description: The email address of the user whose presence you want to
+          fetch.
+        schema:
+          type: string
+        example: iago@zulip.com
+        required: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    presence:
+                      type: object
+                      description: An object containing the presence details
+                        for every client the user has logged into.
+                - example:
+                    {
+                        "presence": {
+                            "website": {
+                                "timestamp": 1532697622,
+                                "status": "active",
+                                "pushable": false,
+                                "client": "website"
+                            },
+                            "ZulipMobile": {
+                                "timestamp": 1522687421,
+                                "status": "active",
+                                "pushable": false,
+                                "client": "ZulipMobile"
+                            },
+                            "aggregated": {
+                                "timestamp": 1532697622,
+                                "status": "active",
+                                "client": "website"
+                            }
+                        },
+                        "result": "success",
+                        "msg": ""
+                    }
   /users/me/{stream_id}/topics:
     get:
       description: Get all the topics in a specific stream.