scheduled-messages: Add API documentation for new endpoint.

Part of splitting creating and editing scheduled messages.
Final commit. Should be merged with previous commits in series.

Updates the API documentation for the new endpoint for editing
scheduled messages.

api_docs/changelog.md

@@ -20,6 +20,15 @@ format used by the Zulip server that they are interacting with.
 
 ## Changes in Zulip 7.0
 
+**Feature level 184**
+
+* [`PATCH /scheduled_messages/<int:scheduled_message_id>`](/api/update-scheduled-message):
+  Added new endpoint for editing an existing scheduled message.
+* [`POST /scheduled_messages`](/api/create-scheduled-message):
+  Removed optional `scheduled_message_id` parameter, which had
+  been a previous way for clients to support editing an existing
+  scheduled message.
+
 **Feature level 183**
 
 * [`POST /register`](/api/register-queue): Removed the
@@ -56,7 +65,7 @@ format used by the Zulip server that they are interacting with.
 
 **Feature level 179**
 
-* [`POST /scheduled_messages`](/api/create-or-update-scheduled-message):
+* [`POST /scheduled_messages`](/api/create-scheduled-message):
   Added new endpoint to create and edit scheduled messages.
 * [`GET /events`](/api/get-events):
   Added `scheduled_messages` events sent to clients when a user creates,

api_docs/create-scheduled-message.md

@@ -17,35 +17,17 @@ curl -X POST {{ api_url }}/v1/scheduled_messages \
     --data-urlencode type=stream \
     --data-urlencode to=9 \
     --data-urlencode topic=Hello \
-    --data-urlencode 'content=Thank you for' \
+    --data-urlencode 'content=Nice to meet everyone!' \
     --data-urlencode scheduled_delivery_timestamp=3165826990
 
-# Update a scheduled stream message
-curl -X POST {{ api_url }}/v1/scheduled_messages \
-    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
-    --data-urlencode type=stream \
-    --data-urlencode to=9 \
-    --data-urlencode 'topic=Welcome aboard' \
-    --data-urlencode 'content=Thank you for the help!' \
-    --data-urlencode scheduled_delivery_timestamp=3165856990 \
-    --data-urlencode scheduled_message_id=1
-
 # Create a scheduled direct message
 curl -X POST {{ api_url }}/v1/messages \
     -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
     --data-urlencode type=direct \
     --data-urlencode 'to=[9, 10]' \
-    --data-urlencode 'content=Can we meet tomorrow?' \
+    --data-urlencode 'content=Can we meet on Monday?' \
     --data-urlencode scheduled_delivery_timestamp=3165826990
 
-# Update a scheduled direct message
-curl -X POST {{ api_url }}/v1/messages \
-    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
-    --data-urlencode type=direct \
-    --data-urlencode 'to=[9, 10, 11]' \
-    --data-urlencode 'content=Can we meet tomorrow?' \
-    --data-urlencode scheduled_delivery_timestamp=3165856990 \
-    --data-urlencode scheduled_message_id=2
 ```
 
 {end_tabs}

api_docs/include/rest-endpoints.md

@@ -20,7 +20,8 @@
 #### Scheduled messages
 
 * [Get scheduled messages](/api/get-scheduled-messages)
-* [Create or edit a scheduled message](/api/create-or-update-scheduled-message)
+* [Create a scheduled message](/api/create-scheduled-message)
+* [Edit a scheduled message](/api/update-scheduled-message)
 * [Delete a scheduled message](/api/delete-scheduled-message)
 
 #### Drafts

version.py

@@ -33,7 +33,7 @@ DESKTOP_WARNING_VERSION = "5.4.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 = 183
+API_FEATURE_LEVEL = 184
 
 # 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/zulip.yaml

@@ -5169,19 +5169,18 @@ paths:
                           ],
                       }
     post:
-      operationId: create-or-update-scheduled-message
+      operationId: create-scheduled-message
       tags: ["scheduled_messages"]
-      summary: Create or edit scheduled message
+      summary: Create a scheduled message
       description: |
-        Create a new scheduled message or edit an existing scheduled message.
+        Create a new [scheduled message](/help/schedule-a-message).
 
-        The `scheduled_message_id` parameter determines whether a scheduled
+        **Changes**: In Zulip 7.0 (feature level 184), moved support for
-        message is created or updated. When it is omitted, a new scheduled
+        [editing a scheduled message](/api/update-scheduled-message) to a
-        message is created. When it is specified, the existing scheduled
+        separate API endpoint, which removed the `scheduled_message_id`
-        message with that unique ID is updated for the values passed to the
+        parameter from this endpoint.
-        other endpoint parameters.
 
-        **Changes**: New in Zulip 7.0 (feature level 179).
+        New in Zulip 7.0 (feature level 179).
       parameters:
         - name: type
           in: query
@@ -5235,16 +5234,6 @@ paths:
             type: string
           example: Castle
           allowEmptyValue: true
-        - name: scheduled_message_id
-          in: query
-          schema:
-            type: integer
-          description: |
-            The unique ID of the scheduled message to be updated.
-
-            If omitted, a new scheduled message will be created. Otherwise,
-            the existing scheduled message with this unique ID will be updated.
-          example: 1
         - name: scheduled_delivery_timestamp
           in: query
           schema:
@@ -5281,6 +5270,134 @@ paths:
                         "scheduled_message_id": 42,
                         "result": "success",
                       }
+        "400":
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - allOf:
+                      - $ref: "#/components/schemas/NonExistingStreamIdError"
+                      - description: |
+                          A typical failed JSON response for when a stream message is scheduled
+                          to be sent to a stream that does not exist:
+                  - allOf:
+                      - $ref: "#/components/schemas/CodedError"
+                      - example:
+                          {
+                            "code": "BAD_REQUEST",
+                            "msg": "Invalid user ID 10",
+                            "result": "error",
+                          }
+                        description: |
+                          A typical failed JSON response for when a direct message is scheduled
+                          to be sent to a user that does not exist:
+  /scheduled_messages/{scheduled_message_id}:
+    patch:
+      operationId: update-scheduled-message
+      tags: ["scheduled_messages"]
+      summary: Edit a scheduled message
+      description: |
+        Edit an existing [scheduled message](/help/schedule-a-message).
+
+        **Changes**: New in Zulip 7.0 (feature level 184).
+      parameters:
+        - name: scheduled_message_id
+          in: path
+          schema:
+            type: integer
+          description: |
+            The ID of the scheduled message to update.
+
+            This is different from the unique ID that the message would have
+            after being sent.
+          required: true
+          example: 2
+        - name: type
+          in: query
+          description: |
+            The type of scheduled message to be sent. `"direct"` for a direct
+            message and `"stream"` for a stream message.
+
+            When updating the type of the scheduled message, the `to` parameter
+            is required. And, if updating the type of the scheduled message to
+            `"stream"`, then the `topic` parameter is also required.
+
+            In Zulip 7.0 (feature level 174), `"direct"` was added as the
+            preferred way to indicate the type of a direct message, deprecating
+            the original `"private"`. While `"private"` is supported for
+            scheduling direct messages, clients are encouraged to use to the
+            modern convention because support for `"private"` may eventually
+            be removed.
+          schema:
+            type: string
+            enum:
+              - direct
+              - stream
+              - private
+          example: stream
+        - name: to
+          in: query
+          description: |
+            The scheduled message's tentative target audience.
+
+            For stream messages, the integer ID of the stream.
+            For direct messages, a list containing integer user IDs.
+
+            Required when updating the `type` of the scheduled message.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: integer
+                  - type: array
+                    items:
+                      type: integer
+                    minLength: 1
+              example: 8
+        - name: content
+          in: query
+          description: |
+            The updated content of the scheduled message.
+
+            Clients should use the `max_message_length` returned by the
+            [`POST /register`](/api/register-queue) endpoint to determine
+            the maximum message size.
+          schema:
+            type: string
+          example: Hello
+        - name: topic
+          in: query
+          description: |
+            The updated topic of the scheduled message.
+
+            Required when updating the `type` of the scheduled message to
+            `"stream"`. Ignored when the existing or updated `type` of the
+            scheduled message is `"direct"` (or `"private"`).
+
+            Clients should use the `max_topic_length` returned by the
+            [`POST /register`](/api/register-queue) endpoint to determine
+            the maximum topic length.
+          schema:
+            type: string
+          example: Castle
+        - name: scheduled_delivery_timestamp
+          in: query
+          schema:
+            type: integer
+          description: |
+            The UNIX timestamp for when the message will be sent,
+            in UTC seconds.
+
+            Required when updating a scheduled message that the server
+            has already tried and failed to send. This state is indicated
+            with `"failed": true` in `scheduled_messages` objects; see
+            response description at
+            [`GET /scheduled_messages`](/api/get-scheduled-messages#response).
+          example: 3165826990
+      responses:
+        "200":
+          $ref: "#/components/responses/SimpleSuccess"
         "400":
           description: Bad request.
           content:
@@ -5313,7 +5430,6 @@ paths:
                             "result": "error",
                             "msg": "Scheduled message does not exist",
                           }
-  /scheduled_messages/{scheduled_message_id}:
     delete:
       operationId: delete-scheduled-message
       tags: ["scheduled_messages"]
@@ -5331,8 +5447,8 @@ paths:
           description: |
             The ID of the scheduled message to delete.
 
-            This is different from the unique ID that a message would have
+            This is different from the unique ID that the message would have
-            after it was sent.
+            after being sent.
           required: true
           example: 1
       responses: