From 4dc206ad2e491663eea0d4310013a4aec967b534 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yago=20Gonz=C3=A1lez?= Date: Fri, 10 Aug 2018 02:15:45 +0200 Subject: [PATCH] api docs: Document PATCH /settings/notifications. With significant tweaks by tabbott after rebasing. --- .../api/update-notification-settings.md | 52 +++++++ .../zerver/help/include/rest-endpoints.md | 1 + zerver/lib/api_test_helpers.py | 28 ++-- zerver/openapi/zulip.yaml | 142 ++++++++++++++++++ 4 files changed, 211 insertions(+), 12 deletions(-) create mode 100644 templates/zerver/api/update-notification-settings.md diff --git a/templates/zerver/api/update-notification-settings.md b/templates/zerver/api/update-notification-settings.md new file mode 100644 index 0000000000..ce406407b5 --- /dev/null +++ b/templates/zerver/api/update-notification-settings.md @@ -0,0 +1,52 @@ +# Update notification settings + +This endpoint is used to edit the user's global notification settings. +See [this endpoint](/api/update-subscription-properties) for +per-stream notification settings. + +`PATCH {{ api_url }}/v1/settings/notifications` + +## Usage examples + +{start_tabs} +{tab|python} + +{generate_code_example(python)|/settings/notifications:patch|example} + +{tab|curl} +``` curl +curl -X PATCH {{ api_url }}/v1/settings/notifications \ + -u BOT_EMAIL_ADDRESS:BOT_API_KEY \ + -d "enable_stream_desktop_notifications=true" \ + -d "enable_stream_email_notifications=true" \ + -d "enable_stream_push_notifications=true" \ + -d "enable_stream_sounds=true" \ + -d "enable_desktop_notifications=true" \ + -d "enable_sounds=true" \ + -d "enable_offline_email_notifications=true" \ + -d "enable_offline_push_notifications=true" \ + -d "enable_online_push_notifications=true" \ + -d "enable_digest_emails=true" \ + -d "message_content_in_email_notifications=true" +``` + +{end_tabs} + +## Arguments + +{generate_api_arguments_table|zulip.yaml|/settings/notifications:patch} + +## Response + +#### Return values + +The server will return the settings that have been changed after the request, +with their new value. Please note that this doesn't necessarily mean that it +will return all the settings passed as parameters in the request, but only +those ones that were different than the already existing setting. + +#### Example response + +A typical successful JSON response may look like: + +{generate_code_example|/settings/notifications:patch|fixture(200)} diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md index 5a5e5b3be9..03f8970106 100644 --- a/templates/zerver/help/include/rest-endpoints.md +++ b/templates/zerver/help/include/rest-endpoints.md @@ -32,6 +32,7 @@ * [Set "typing" status](/api/typing) * [Get user presence](/api/get-presence) * [Get all user groups](/api/get-user-groups) +* [Update notification settings](/api/update-notification-settings) #### Server & organizations diff --git a/zerver/lib/api_test_helpers.py b/zerver/lib/api_test_helpers.py index 99c79cbcb4..2fe099272c 100644 --- a/zerver/lib/api_test_helpers.py +++ b/zerver/lib/api_test_helpers.py @@ -762,6 +762,20 @@ def get_server_settings(client): validate_against_openapi_schema(result, '/server_settings', 'get', '200') +def update_notification_settings(client): + # type: (Client) -> None + + # {code_example|start} + # Enable push notifications even when online + request = { + 'enable_offline_push_notifications': True, + 'enable_online_push_notifications': True, + } + result = client.update_notification_settings(request) + # {code_example|end} + + validate_against_openapi_schema(result, '/settings/notifications', 'patch', '200') + def upload_file(client): # type: (Client) -> None path_to_file = os.path.join(ZULIP_DIR, 'zerver', 'tests', 'images', 'img.jpg') @@ -896,17 +910,6 @@ def update_user_group_members(client, group_id): assert result['result'] == 'success' -def update_notification_settings(client): - # type: (Client) -> None - request = { - 'enable_stream_push_notifications': True, - 'enable_offline_push_notifications': False - } - - result = client.update_notification_settings(request) - - assert result['result'] == 'success' - def test_invalid_api_key(client_with_invalid_key): # type: (Client) -> None result = client_with_invalid_key.list_subscriptions() @@ -951,7 +954,6 @@ TEST_FUNCTIONS = { '/users/me/subscriptions:delete': remove_subscriptions, '/users/me/subscriptions/muted_topics:patch': toggle_mute_topic, '/users/me/subscriptions/properties:post': update_subscription_settings, - '/settings/notifications:patch': update_notification_settings, '/users:get': get_members, '/realm/emoji:get': get_realm_emoji, '/realm/emoji/:post': upload_custom_emoji, @@ -961,6 +963,7 @@ TEST_FUNCTIONS = { '/register:post': register_queue, '/events:delete': deregister_queue, '/server_settings:get': get_server_settings, + '/settings/notifications:patch': update_notification_settings, '/user_uploads:post': upload_file, '/users/me/{stream_id}/topics:get': get_stream_topics, '/typing:post': set_typing_status, @@ -1050,6 +1053,7 @@ def test_users(client): create_user(client) get_members(client) get_profile(client) + update_notification_settings(client) upload_file(client) set_typing_status(client) get_user_presence(client) diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 57a92524ff..0f0e3a1c35 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -1783,6 +1783,148 @@ paths: "result": "success", "require_email_format_usernames": true } + /settings/notifications: + patch: + description: Modify the user's preferences for notifications. + parameters: + - name: enable_stream_desktop_notifications + in: query + description: Enable visual desktop notifications for stream messages. + schema: + type: boolean + example: true + - name: enable_stream_email_notifications + in: query + description: Enable email notifications for stream messages. + schema: + type: boolean + example: true + - name: enable_stream_push_notifications + in: query + description: Enable mobile notifications for stream messages. + schema: + type: boolean + example: true + - name: enable_stream_audible_notifications + in: query + description: Enable audible desktop notifications for stream messages. + schema: + type: boolean + example: true + - name: enable_desktop_notifications + in: query + description: Enable visual desktop notifications for private messages + and @-mentions. + schema: + type: boolean + example: true + - name: enable_sounds + in: query + description: Enable audible desktop notifications for private messages + and @-mentions. + schema: + type: boolean + example: true + - name: enable_offline_email_notifications + in: query + description: Enable email notifications for private messages and + @-mentions received when the user is offline. + schema: + type: boolean + example: true + - name: enable_offline_push_notifications + in: query + description: Enable mobile notification for private messages and + @-mentions received when the user is offline. + schema: + type: boolean + example: true + - name: enable_online_push_notifications + in: query + description: Enable mobile notification for private messages and + @-mentions received when the user is online. + schema: + type: boolean + example: true + - name: enable_digest_emails + in: query + description: Enable digest emails when the user is away. + schema: + type: boolean + example: true + - name: message_content_in_email_notifications + in: query + description: Include the message's content in missed messages email + notifications. + schema: + type: boolean + example: true + security: + - basicAuth: [] + responses: + '200': + description: Success. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/JsonSuccess' + - properties: + enable_desktop_notifications: + type: boolean + description: The setting for + `enable_desktop_notifications`, if it was changed in + this request. + enable_digest_emails: + type: boolean + description: The setting for `enable_digest_emails`, if + it was changed in this request. + enable_offline_email_notifications: + type: boolean + description: The setting for + `enable_offline_email_notifications`, if it was changed + in this request. + enable_offline_push_notifications: + type: boolean + description: The setting for + `enable_offline_push_notifications`, if it was changed + in this request. + enable_online_push_notifications: + type: boolean + description: The setting for + `enable_online_push_notifications`, if it was changed + in this request. + enable_sounds: + type: boolean + description: The setting for `enable_sounds`, if it was + changed in this request. + enable_stream_email_notifications: + type: boolean + description: The setting for + `enable_stream_email_notifications`, if it was changed + in this request. + enable_stream_push_notifications: + type: boolean + description: The setting for + `enable_stream_push_notifications`, if it was changed + in this request. + enable_stream_audible_notifications: + type: boolean + description: The setting for + `enable_stream_audible_notifications`, if it was changed in this + request. + message_content_in_email_notifications: + type: boolean + description: The setting for + `message_content_in_email_notifications`, if it was + changed in this request. + - example: + { + "enable_offline_push_notifications": true, + "enable_online_push_notifications": true, + "msg": "", + "result": "success" + } /streams: get: description: Get all streams that the user has access to.