Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Lauryn Menard 2023-05-16 21:20:49 +02:00 committed by Tim Abbott
parent 957382253a
commit 0c09a4fffe
5 changed files with 153 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
api_docs/changelog.md
View File

@ -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,

22
api_docs/create-or-update-scheduled-messages.md → api_docs/create-scheduled-message.md
View File

@ -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}

3
api_docs/include/rest-endpoints.md
View File

@ -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

2
version.py
View File

@ -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

160
zerver/openapi/zulip.yaml
View File

@ -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
message is created or updated. When it is omitted, a new scheduled
message is created. When it is specified, the existing scheduled
message with that unique ID is updated for the values passed to the
other endpoint parameters.
**Changes**: In Zulip 7.0 (feature level 184), moved support for
[editing a scheduled message](/api/update-scheduled-message) to a
separate API endpoint, which removed the `scheduled_message_id`
parameter from this endpoint.
**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
after it was sent.
This is different from the unique ID that the message would have
after being sent.
required: true
example: 1
responses: