From 3bdc8f9946f288171f94e0d5896aa1d20976beaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yago=20Gonz=C3=A1lez?= Date: Tue, 3 Jul 2018 20:22:53 +0200 Subject: [PATCH] api: Document the GET /realm/emoji endpoint. --- templates/zerver/api/get-org-emoji.md | 79 +++++++++++++++++++ .../zerver/help/include/rest-endpoints.md | 1 + zerver/lib/api_test_helpers.py | 11 +++ zerver/openapi/zulip.yaml | 36 +++++++++ 4 files changed, 127 insertions(+) create mode 100644 templates/zerver/api/get-org-emoji.md diff --git a/templates/zerver/api/get-org-emoji.md b/templates/zerver/api/get-org-emoji.md new file mode 100644 index 0000000000..4ae1079cd4 --- /dev/null +++ b/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 + +
+ +
+ +
+ +``` +curl {{ api_url }}/v1/realm/emoji \ + -u BOT_EMAIL_ADDRESS:BOT_API_KEY +``` + +
+ +
+ +{generate_code_example(python)|/realm/emoji:get|example} + +
+ +
+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); +``` +
+ +
+ +
+ +## 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)} diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md index a7444e49cc..f0750beeb1 100644 --- a/templates/zerver/help/include/rest-endpoints.md +++ b/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) diff --git a/zerver/lib/api_test_helpers.py b/zerver/lib/api_test_helpers.py index d5161a69a7..e06b1d2712 100644 --- a/zerver/lib/api_test_helpers.py +++ b/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/: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 diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 540f0a7a0a..a70bda6ad1 100644 --- a/zerver/openapi/zulip.yaml +++ b/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.