api: Document the GET /realm/emoji endpoint.

templates/zerver/api/get-org-emoji.md

@@ -0,0 +1,79 @@
+# Get all custom emoji
+
+Get all the custom emoji in the user's organization.
+
+`GET {{ api_url }}/v1/realm/emoji`
+
+## Usage examples
+
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="python">Python</li>
+<li data-language="javascript">JavaScript</li>
+<li data-language="curl">curl</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl {{ api_url }}/v1/realm/emoji \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+{generate_code_example(python)|/realm/emoji:get|example}
+
+</div>
+
+<div data-language="javascript" markdown="1">
+More examples and documentation can be found [here](https://github.com/zulip/zulip-js).
+```js
+const zulip = require('zulip-js');
+
+// Download zuliprc-dev from your dev server
+const config = {
+    zuliprc: 'zuliprc-dev',
+};
+
+zulip(config).then((client) => {
+    return client.emojis.retrieve();
+}).then(console.log);
+```
+</div>
+
+</div>
+
+</div>
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/realm/emoji:get}
+
+## Response
+
+#### Return values
+
+* `emoji`: An object that contains `emoji` objects, each identified with their
+    emoji ID as the key, and containing the following properties:
+    * `id`: The ID for this emoji, same as the object's key.
+    * `name`: The user-friendly name for this emoji. Users in the organization
+        can use this emoji by writing this name between colons (`:name:`).
+    * `source_url`: The path relative to the organization's URL where the
+        emoji's image can be found.
+    * `deactivated`: Whether the emoji has been deactivated or not.
+    * `author`: An object describing the user who created the custom emoji,
+        with the following fields:
+        * `id`: The creator's user ID.
+        * `email`: The creator's email address.
+        * `full_name`: The creator's full name.
+
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/realm/emoji:get|fixture(200)}

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

@@ -35,6 +35,7 @@
 * [List organization filters](/api/list-org-filters)
 * [Create organization filters](/api/create-org-filters)
 * [Remove organization filters](/api/remove-org-filters)
+* [Get all custom emoji](/api/get-org-emoji)
 
 #### Real-time events
 * [Real time events API](/api/real-time-events)

zerver/lib/api_test_helpers.py

@@ -546,6 +546,15 @@ def get_message_history(client, message_id):
     validate_against_openapi_schema(result, '/messages/{message_id}/history',
                                     'get', '200')
 
+def get_realm_emoji(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    result = client.get_realm_emoji()
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/realm/emoji', 'GET', '200')
+
 def register_queue(client):
     # type: (Client) -> str
 
@@ -674,6 +683,7 @@ TEST_FUNCTIONS = {
     '/users/me/subscriptions:delete': remove_subscriptions,
     '/users/me/subscriptions/muted_topics:patch': toggle_mute_topic,
     '/users:get': get_members,
+    '/realm/emoji:get': get_realm_emoji,
     '/realm/filters:get': get_realm_filters,
     '/realm/filters:post': add_realm_filter,
     '/realm/filters/<filter_id>:delete': remove_realm_filter,
@@ -792,6 +802,7 @@ def test_server_organizations(client):
     add_realm_filter(client)
     get_server_settings(client)
     remove_realm_filter(client)
+    get_realm_emoji(client)
 
 def test_errors(client):
     # type: (Client) -> None

zerver/openapi/zulip.yaml

@@ -1219,6 +1219,42 @@ paths:
                           "msg": "Topic is not muted",
                           "result": "error"
                       }
+  /realm/emoji:
+    get:
+      description: Get all the custom emoji in the user's realm.
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    emoji:
+                      type: object
+                      description: An object that contains `emoji` objects,
+                        each identified with their emoji ID as the key.
+                - example:
+                    {
+                        "result": "success",
+                        "msg": "",
+                        "emoji": {
+                            "1": {
+                                "id": "1",
+                                "name": "green_tick",
+                                "source_url": "/user_avatars/1/emoji/images/1.png",
+                                "deactivated": false,
+                                "author": {
+                                    "id": 5,
+                                    "email": "iago@zulip.com",
+                                    "full_name": "Iago"
+                                }
+                            }
+                        }
+                    }
   /realm/filters:
     get:
       description: Fetch all the filters set up for the user's organization.