api: Return 'user_id' in 'POST /users' response.

This adds 'user_id' to the simple success response for 'POST /users'
api endpoint, to make it convenient for API clients to get details
about users they just created.  Appropriate changes have been made in
the docs and test_users.py.

Fixes #16072.

templates/zerver/api/changelog.md

@@ -15,6 +15,8 @@ below features are supported.
 * [`GET users/me/subscriptions`](/api/get-subscriptions), [`GET
   /streams`](/api/get-streams): Added `date_created` to Stream
   objects.
+* [`POST /users`](/api/create-user), `POST /bots`: The ID of the newly
+  created user is now returned in the response.
 
 Feature levels 28 and 29 are reserved for future use in 3.x bug fix
 releases.

templates/zerver/api/create-user.md

@@ -27,6 +27,10 @@ More examples and documentation can be found [here](https://github.com/zulip/zul
 
 ## Response
 
+#### Return values
+
+{generate_return_values_table|zulip.yaml|/users:post}
+
 #### Example response
 
 A typical successful JSON response may look like:

version.py

@@ -29,7 +29,7 @@ DESKTOP_WARNING_VERSION = "5.2.0"
 #
 # Changes should be accompanied by documentation explaining what the
 # new level means in templates/zerver/api/changelog.md.
-API_FEATURE_LEVEL = 27
+API_FEATURE_LEVEL = 30
 
 # 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/openapi/zulip.yaml

@@ -4081,7 +4081,16 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/JsonSuccess"
+                allOf:
+                  - $ref: "#/components/schemas/JsonSuccess"
+                  - properties:
+                      user_id:
+                        type: integer
+                        description: |
+                          The ID assigned to the newly created user.
+
+                          **Changes**: New in Zulip 4.0 (feature level 30).
+                  - example: {"msg": "", "result": "success", "user_id": 25}
         "400":
           description: Bad request.
           content:

zerver/tests/test_bots.py

@@ -175,6 +175,7 @@ class BotTest(ZulipTestCase, UploadSerializeMixin):
             if e['event']['type'] == 'realm_bot'
         ]
 
+        self.assertEqual(result["user_id"], bot.id)
         self.assertEqual(
             dict(
                 type='realm_bot',

zerver/tests/test_users.py

@@ -823,7 +823,9 @@ class AdminCreateUserTest(ZulipTestCase):
 
         # Romeo is a newly registered user
         new_user = get_user_by_delivery_email('romeo@zulip.net', get_realm('zulip'))
+        result = orjson.loads(result.content)
         self.assertEqual(new_user.full_name, 'Romeo Montague')
+        self.assertEqual(new_user.id, result['user_id'])
 
         # Make sure the recipient field is set correctly.
         self.assertEqual(new_user.recipient, Recipient.objects.get(type=Recipient.PERSONAL,

zerver/views/users.py

@@ -413,6 +413,7 @@ def add_bot_backend(
     api_key = get_api_key(bot_profile)
 
     json_result = dict(
+        user_id=bot_profile.id,
         api_key=api_key,
         avatar_url=avatar_url(bot_profile),
         default_sending_stream=get_stream_name(bot_profile.default_sending_stream),
@@ -521,8 +522,8 @@ def create_user_backend(
     if not check_password_strength(password):
         return json_error(PASSWORD_TOO_WEAK_ERROR)
 
-    do_create_user(email, password, realm, full_name, acting_user=user_profile)
-    return json_success()
+    target_user = do_create_user(email, password, realm, full_name, acting_user=user_profile)
+    return json_success({'user_id': target_user.id})
 
 def get_profile_backend(request: HttpRequest, user_profile: UserProfile) -> HttpResponse:
     raw_user_data = get_raw_user_data(user_profile.realm, user_profile,