api: Add "users/<int:user_id>/status" endpoint.

The documentation Creates a shared UserStatus schema that's used for
the return value of this new endpoint and for the existing user_status
objects returned by the register queue endpoint.

Co-authored-by: Suyash Vardhan Mathur <suyash.mathur@research.iiit.ac.in>

Fixes #19079.

api_docs/changelog.md

@@ -20,6 +20,12 @@ format used by the Zulip server that they are interacting with.
 
 ## Changes in Zulip 9.0
 
+**Feature level 262**:
+
+* [`GET /users/{user_id}/status`](/api/get-user-status): Added a new
+  endpoint to fetch an individual user's currently set
+  [status](/help/status-and-availability).
+
 **Feature level 261**
 
 * [`POST /invites`](/api/send-invites),

api_docs/include/rest-endpoints.md

@@ -69,6 +69,7 @@
 * [Deactivate own user](/api/deactivate-own-user)
 * [Set "typing" status](/api/set-typing-status)
 * [Get user presence](/api/get-user-presence)
+* [Get a user's status](/api/get-user-status)
 * [Get presence of all users](/api/get-presence)
 * [Get attachments](/api/get-attachments)
 * [Delete an attachment](/api/remove-attachment)

version.py

@@ -33,7 +33,7 @@
 # Changes should be accompanied by documentation explaining what the
 # new level means in api_docs/changelog.md, as well as "**Changes**"
 # entries in the endpoint's documentation in `zulip.yaml`.
-API_FEATURE_LEVEL = 261
+API_FEATURE_LEVEL = 262
 
 # Bump the minor PROVISION_VERSION to indicate that folks should provision
 # only when going from an old version of the code to a newer version. Bump

zerver/lib/user_status.py

@@ -113,3 +113,22 @@ def update_user_status(
         user_profile_id=user_profile_id,
         defaults=defaults,
     )
+
+
+def get_user_status(user_profile: UserProfile) -> UserInfoDict:
+    status_set_by_user = (
+        UserStatus.objects.filter(user_profile=user_profile)
+        .values(
+            "user_profile_id",
+            "user_profile__presence_enabled",
+            "status_text",
+            "emoji_name",
+            "emoji_code",
+            "reaction_type",
+        )
+        .first()
+    )
+
+    if not status_set_by_user:
+        return {}
+    return format_user_status(status_set_by_user)

zerver/openapi/python_examples.py

@@ -195,6 +195,20 @@ def get_user_presence(client: Client) -> None:
     validate_against_openapi_schema(result, "/users/{user_id_or_email}/presence", "get", "200")
 
 
+@openapi_test_function("/users/{user_id}/status:get")
+def get_user_status(client: Client) -> None:
+    # {code_example|start}
+    # Get the status currently set by a user.
+    user_id = 11
+    result = client.call_endpoint(
+        url=f"/users/{user_id}/status",
+        method="GET",
+    )
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, "/users/{user_id}/status", "get", "200")
+
+
 @openapi_test_function("/users/me/presence:post")
 def update_presence(client: Client) -> None:
     request = {
@@ -1701,6 +1715,7 @@ def test_users(client: Client, owner_client: Client) -> None:
     reactivate_user(client)
     update_user(client)
     update_status(client)
+    get_user_status(client)
     get_user_by_email(client)
     get_subscription_status(client)
     get_profile(client)

zerver/openapi/zulip.yaml

@@ -8416,6 +8416,68 @@ paths:
         "200":
           $ref: "#/components/responses/SimpleSuccess"
 
+  /users/{user_id}/status:
+    get:
+      operationId: get-user-status
+      summary: Get a user's status
+      tags: ["users"]
+      description: |
+        Get the [status](/help/status-and-availability) currently set by a
+        user in the organization.
+
+        **Changes**: New in Zulip 9.0 (feature level 262). Previously,
+        user statuses could only be fetched via the [`POST
+        /register`](/api/register-queue) endpoint.
+      parameters:
+        - $ref: "#/components/parameters/UserId"
+      responses:
+        "200":
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/JsonSuccessBase"
+                  - additionalProperties: false
+                    properties:
+                      result: {}
+                      msg: {}
+                      ignored_parameters_unsupported: {}
+                      status:
+                        allOf:
+                          - description: |
+                              The status set by the user. Note that, if the user doesn't have a status
+                              currently set, then the returned dictionary will be empty as none of the
+                              keys listed below will be present.
+                          - $ref: "#/components/schemas/UserStatus"
+
+                    example:
+                      {
+                        "result": "success",
+                        "msg": "",
+                        "status":
+                          {
+                            "status_text": "on vacation",
+                            "emoji_name": "car",
+                            "emoji_code": "1f697",
+                            "reaction_type": "unicode_emoji",
+                          },
+                      }
+        "400":
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/CodedError"
+                  - example:
+                      {
+                        "result": "error",
+                        "msg": "No such user",
+                        "code": "BAD_REQUEST",
+                      }
+                    description: |
+                      An example JSON error response when the user does not exist:
   /users/{user_id_or_email}/presence:
     get:
       operationId: get-user-presence
@@ -13652,63 +13714,11 @@ paths:
                           **Changes**: The emoji parameters are new in Zulip 5.0 (feature level 86).
                           Previously, Zulip did not support emoji associated with statuses.
                         additionalProperties:
-                          description: |
-                            `{user_id}`: Object containing the status details of a user
-                            with the key of the object being the ID of the user.
-                          type: object
-                          additionalProperties: false
-                          properties:
-                            away:
-                              type: boolean
-                              deprecated: true
-                              description: |
-                                If present, the user has marked themself "away".
-
-                                **Changes**: Deprecated in Zulip 6.0 (feature level 148);
-                                starting with that feature level, `away` is a legacy way to
-                                access the user's `presence_enabled` setting, with
-                                `away = !presence_enabled`. To be removed in a future release.
-                            status_text:
-                              type: string
-                              description: |
-                                If present, the text content of the user's status message.
-                            emoji_name:
-                              type: string
-                              description: |
-                                If present, the name for the emoji to associate with the user's status.
-
-                                **Changes**: New in Zulip 5.0 (feature level 86).
-                            emoji_code:
-                              type: string
-                              description: |
-                                If present, a unique identifier, defining the specific emoji codepoint
-                                requested, within the namespace of the `reaction_type`.
-
-                                **Changes**: New in Zulip 5.0 (feature level 86).
-                            reaction_type:
-                              type: string
-                              enum:
-                                - unicode_emoji
-                                - realm_emoji
-                                - zulip_extra_emoji
-                              description: |
-                                If present, a string indicating the type of emoji. Each emoji
-                                `reaction_type` has an independent namespace for values of `emoji_code`.
-
-                                Must be one of the following values:
-
-                                - `unicode_emoji` : In this namespace, `emoji_code` will be a
-                                  dash-separated hex encoding of the sequence of Unicode codepoints
-                                  that define this emoji in the Unicode specification.
-
-                                - `realm_emoji` : In this namespace, `emoji_code` will be the ID of
-                                  the uploaded [custom emoji](/help/custom-emoji).
-
-                                - `zulip_extra_emoji` : These are special emoji included with Zulip.
-                                  In this namespace, `emoji_code` will be the name of the emoji (e.g.
-                                  "zulip").
-
-                                **Changes**: New in Zulip 5.0 (feature level 86).
+                          allOf:
+                            - description: |
+                                `{user_id}`: Object containing the status details of a user
+                                with the key of the object being the ID of the user.
+                            - $ref: "#/components/schemas/UserStatus"
                       user_settings:
                         type: object
                         description: |
@@ -21100,6 +21110,61 @@ components:
             **Changes**: Starting with Zulip 7.0 (feature level 178), always
             `false` when present as the server no longer stores which client
             submitted presence data.
+    UserStatus:
+      type: object
+      additionalProperties: false
+      properties:
+        away:
+          type: boolean
+          deprecated: true
+          description: |
+            If present, the user has marked themself "away".
+
+            **Changes**: Deprecated in Zulip 6.0 (feature level 148);
+            starting with that feature level, `away` is a legacy way to
+            access the user's `presence_enabled` setting, with
+            `away = !presence_enabled`. To be removed in a future release.
+        status_text:
+          type: string
+          description: |
+            If present, the text content of the user's status message.
+        emoji_name:
+          type: string
+          description: |
+            If present, the name for the emoji to associate with the user's status.
+
+            **Changes**: New in Zulip 5.0 (feature level 86).
+        emoji_code:
+          type: string
+          description: |
+            If present, a unique identifier, defining the specific emoji codepoint
+            requested, within the namespace of the `reaction_type`.
+
+            **Changes**: New in Zulip 5.0 (feature level 86).
+        reaction_type:
+          type: string
+          enum:
+            - unicode_emoji
+            - realm_emoji
+            - zulip_extra_emoji
+          description: |
+            If present, a string indicating the type of emoji. Each emoji
+            `reaction_type` has an independent namespace for values of `emoji_code`.
+
+            Must be one of the following values:
+
+            - `unicode_emoji` : In this namespace, `emoji_code` will be a
+              dash-separated hex encoding of the sequence of Unicode codepoints
+              that define this emoji in the Unicode specification.
+
+            - `realm_emoji` : In this namespace, `emoji_code` will be the ID of
+              the uploaded [custom emoji](/help/custom-emoji).
+
+            - `zulip_extra_emoji` : These are special emoji included with Zulip.
+              In this namespace, `emoji_code` will be the name of the emoji (e.g.
+              "zulip").
+
+            **Changes**: New in Zulip 5.0 (feature level 86).
     Draft:
       type: object
       description: |