docs: Add documentation for delete emoji endpoint.

This endpoint was previously marked as `intentionally_undocumented`
but that was mistake.

Removed `intentionally_undocumented` and added proper documentation
with valid `python_example` for this Endpoint.

Fixes: #24084

api_docs/changelog.md

@@ -20,6 +20,11 @@ format used by the Zulip server that they are interacting with.
 
 ## Changes in Zulip 8.0
 
+**Feature level 190**
+
+* [`DELETE /realm/emoji/{emoji_name}`](/api/deactivate-custom-emoji): This endpoint
+  now returns an HTTP status code of 404 when an emoji does not exist, instead of 400.
+
 **Feature level 189**
 
 * [`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults),

api_docs/include/rest-endpoints.md

@@ -96,6 +96,7 @@
 * [Remove a code playground](/api/remove-code-playground)
 * [Get all custom emoji](/api/get-custom-emoji)
 * [Upload custom emoji](/api/upload-custom-emoji)
+* [Deactivate custom emoji](/api/deactivate-custom-emoji)
 * [Get all custom profile fields](/api/get-custom-profile-fields)
 * [Reorder custom profile fields](/api/reorder-custom-profile-fields)
 * [Create a custom profile field](/api/create-custom-profile-field)

version.py

@@ -33,7 +33,7 @@ DESKTOP_WARNING_VERSION = "5.9.3"
 # 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 = 189
+API_FEATURE_LEVEL = 190
 
 # 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/openapi.py

@@ -23,7 +23,6 @@ OPENAPI_SPEC_PATH = os.path.abspath(
 # A list of endpoint-methods such that the endpoint
 # has documentation but not with this particular method.
 EXCLUDE_UNDOCUMENTED_ENDPOINTS = {
-    ("/realm/emoji/{emoji_name}", "delete"),
     ("/users", "patch"),
 }
 # Consists of endpoints with some documentation remaining.

zerver/openapi/python_examples.py

@@ -1387,6 +1387,17 @@ def upload_custom_emoji(client: Client) -> None:
     validate_against_openapi_schema(result, "/realm/emoji/{emoji_name}", "post", "200")
 
 
+@openapi_test_function("/realm/emoji/{emoji_name}:delete")
+def delete_custom_emoji(client: Client) -> None:
+    # {code_example|start}
+    # Delete a custom emoji.
+    emoji_name = "my_custom_emoji"
+    result = client.call_endpoint(f"realm/emoji/{emoji_name}", method="DELETE")
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, "/realm/emoji/{emoji_name}", "delete", "200")
+
+
 @openapi_test_function("/users/me/alert_words:get")
 def get_alert_words(client: Client) -> None:
     # {code_example|start}
@@ -1624,6 +1635,7 @@ def test_server_organizations(client: Client) -> None:
     remove_realm_playground(client)
     get_realm_emoji(client)
     upload_custom_emoji(client)
+    delete_custom_emoji(client)
     get_realm_profile_fields(client)
     reorder_realm_profile_fields(client)
     create_realm_profile_field(client)

zerver/openapi/zulip.yaml

@@ -9174,6 +9174,48 @@ paths:
       responses:
         "200":
           $ref: "#/components/responses/SimpleSuccess"
+    delete:
+      operationId: deactivate-custom-emoji
+      summary: Deactivate custom emoji
+      tags: ["server_and_organizations"]
+      description: |
+        [Deactivate a custom emoji](/help/custom-emoji#deactivate-custom-emoji) from
+        the user's organization.
+
+        Users can only deactivate custom emoji that they added themselves except for
+        organization administrators, who can deactivate any custom emoji.
+
+        Note that deactivated emoji will still be visible in old messages, reactions,
+        user statuses and stream descriptions.
+
+        **Changes**: Before Zulip 8.0 (feature level 190), this endpoint returned an
+        HTTP status code of 400 when the emoji did not exist, instead of 404.
+      parameters:
+        - name: emoji_name
+          required: true
+          in: path
+          description: |
+            The name of the custom emoji to deactivate.
+          schema:
+            type: string
+          example: green_tick
+      responses:
+        "200":
+          $ref: "#/components/responses/SimpleSuccess"
+        "404":
+          description: Not Found.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/JsonError"
+                  - description: |
+                      JSON response for when no emoji exists with the provided name.
+                    example:
+                      {
+                        "result": "error",
+                        "msg": "Emoji 'green_tick' does not exist",
+                      }
 
   /realm/emoji:
     get:

zerver/tests/test_realm_emoji.py

@@ -282,7 +282,7 @@ class RealmEmojiTest(ZulipTestCase):
     def test_delete_exception(self) -> None:
         self.login("iago")
         result = self.client_delete("/json/realm/emoji/invalid_emoji")
-        self.assert_json_error(result, "Emoji 'invalid_emoji' does not exist")
+        self.assert_json_error(result, "Emoji 'invalid_emoji' does not exist", status_code=404)
 
     def test_multiple_upload(self) -> None:
         self.login("iago")

zerver/views/realm_emoji.py

@@ -6,7 +6,7 @@ from django.utils.translation import gettext as _
 from zerver.actions.realm_emoji import check_add_realm_emoji, do_remove_realm_emoji
 from zerver.decorator import require_member_or_admin
 from zerver.lib.emoji import check_remove_custom_emoji, check_valid_emoji_name, name_to_codepoint
-from zerver.lib.exceptions import JsonableError
+from zerver.lib.exceptions import JsonableError, ResourceNotFoundError
 from zerver.lib.request import REQ, has_request_variables
 from zerver.lib.response import json_success
 from zerver.models import RealmEmoji, UserProfile
@@ -56,7 +56,7 @@ def delete_emoji(request: HttpRequest, user_profile: UserProfile, emoji_name: st
     if not RealmEmoji.objects.filter(
         realm=user_profile.realm, name=emoji_name, deactivated=False
     ).exists():
-        raise JsonableError(_("Emoji '{}' does not exist").format(emoji_name))
+        raise ResourceNotFoundError(_("Emoji '{}' does not exist").format(emoji_name))
     check_remove_custom_emoji(user_profile, emoji_name)
     do_remove_realm_emoji(user_profile.realm, emoji_name, acting_user=user_profile)
     return json_success(request)

zproject/urls.py

@@ -265,9 +265,8 @@ v1_api_and_json_patterns = [
     rest_path(
         "realm/emoji/<path:emoji_name>",
         POST=upload_emoji,
-        DELETE=(delete_emoji, {"intentionally_undocumented"}),
+        DELETE=delete_emoji,
     ),
-    # this endpoint throws a status code 400 JsonableError when it should be a 404.
     # realm/icon -> zerver.views.realm_icon
     rest_path("realm/icon", POST=upload_icon, DELETE=delete_icon_backend, GET=get_icon_backend),
     # realm/logo -> zerver.views.realm_logo