api docs: Document the POST /users/me/subscriptions/properties endpoint.

templates/zerver/api/update-subscription-properties.md

@@ -0,0 +1,71 @@
+# Update subscription properties
+
+This endpoint is used to update the user's personal settings for the
+streams they are subscribed to, including muting, color, pinning, and
+per-stream notification settings.
+
+`POST {{ api_url }}/v1/users/me/subscriptions/properties`
+
+## Usage examples
+
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="python">Python</li>
+<li data-language="curl">curl</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl -X POST {{ api_url }}/v1/users/me/subscriptions/properties \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+    -d 'subscription_data=[{"stream_id": 1, \
+                            "property": "pin_to_top", \
+                            "value": true}, \
+                           {"stream_id": 3, \
+                            "property": "color", \
+                            "value": 'f00'}]'
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+{generate_code_example(python)|/users/me/subscriptions/properties:post|example}
+
+</div>
+
+</div>
+
+</div>
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/users/me/subscriptions/properties:post}
+
+The possible values for each `property` and `value` pairs are:
+
+* `color` (string): the hex value of the user's display color for the stream.
+* `in_home_view` (boolean): whether the stream should be visible in the home
+    view (`true`) or muted and thus hidden from the home view (`false`).
+* `pin_to_top` (boolean): whether to pin the stream at the top of the stream list.
+* `desktop_notifications` (boolean): whether to show desktop notifications
+    for all messages sent to the stream.
+* `audible_notifications` (boolean): whether to play a sound
+  notification for all messages sent to the stream.
+* `push_notifications` (boolean): whether to trigger a mobile push
+    notification for all messages sent to the stream.
+
+## Response
+
+#### Return values
+
+* `subscription_data`: The same `subscription_data` object sent by the client
+    for the request, confirming the changes made.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/users/me/subscriptions/properties:post|fixture(200)}

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

@@ -17,6 +17,7 @@
 * [Get all streams](/api/get-all-streams)
 * [Get subscribed streams](/api/get-subscribed-streams)
 * [Add subscriptions](/api/add-subscriptions)
+* [Update subscription settings](/api/update-subscription-properties)
 * [Remove subscriptions](/api/remove-subscriptions)
 * [Get topics in a stream](/api/get-stream-topics)
 * [Topic muting](/api/mute-topics)

zerver/lib/api_test_helpers.py

@@ -374,6 +374,28 @@ def mark_topic_as_read(client):
 
     validate_against_openapi_schema(result, '/mark_stream_as_read', 'post', '200')
 
+def update_subscription_settings(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # Update the user's subscription in stream #1 to pin it to the top of the
+    # stream list; and in stream #3 to have the hex color "f00"
+    request = [{
+        'stream_id': 1,
+        'property': 'pin_to_top',
+        'value': True
+    }, {
+        'stream_id': 3,
+        'property': 'color',
+        'value': 'f00'
+    }]
+    result = client.update_subscription_settings(request)
+    # {code_example|end}
+
+    validate_against_openapi_schema(result,
+                                    '/users/me/subscriptions/properties',
+                                    'POST', '200')
+
 def render_message(client):
     # type: (Client) -> None
 
@@ -759,6 +781,7 @@ TEST_FUNCTIONS = {
     '/users/{email}/presence:get': get_user_presence,
     '/users/me/subscriptions:delete': remove_subscriptions,
     '/users/me/subscriptions/muted_topics:patch': toggle_mute_topic,
+    '/users/me/subscriptions/properties:post': update_subscription_settings,
     '/users:get': get_members,
     '/realm/emoji:get': get_realm_emoji,
     '/realm/filters:get': get_realm_filters,
@@ -860,6 +883,7 @@ def test_streams(client, nonadmin_client):
     get_subscribers(client)
     remove_subscriptions(client)
     toggle_mute_topic(client)
+    update_subscription_settings(client)
     get_stream_topics(client, 1)
 
     test_user_not_authorized_error(nonadmin_client)

zerver/openapi/zulip.yaml

@@ -1384,6 +1384,58 @@ paths:
                             }
                         }
                     }
+  /users/me/subscriptions/properties:
+    post:
+      description: Make bulk modifications of the subscription properties on
+        one or more streams the user is subscribed to.
+      parameters:
+      - name: subscription_data
+        in: query
+        description: A list of objects that describe the changes that should
+          be applied in each subscription. Each object represents a
+          subscription, and must have a `stream_id` key that identifies the
+          stream, as well as the `property` being modified and its new
+          `value`.
+        schema:
+          type: array
+          items:
+            type: object
+        example: [{"stream_id": 1, "property": "pin_to_top", "value": true}]
+        required: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    subscription_data:
+                      type: array
+                      items:
+                        type: object
+                      description: The same `subscription_data` object sent
+                        by the client for the request.
+                - example:
+                    {
+                        "subscription_data": [
+                            {
+                                "property": "pin_to_top",
+                                "value": true,
+                                "stream_id": 1
+                            },
+                            {
+                                "property": "color",
+                                "value": 'f00',
+                                "stream_id": 3
+                            }
+                        ],
+                        "result": "success",
+                        "msg": ""
+                    }
   /realm/filters:
     get:
       description: Fetch all the filters set up for the user's organization.