diff --git a/sections/cloud_files.md b/sections/cloud_files.md index d98a629..5560cce 100644 --- a/sections/cloud_files.md +++ b/sections/cloud_files.md @@ -242,8 +242,11 @@ Update a cloud file Update accepts `title`, `url`, `service`, and `description`, and all four are sent on every update — the controller replaces the recordable on each call rather than -patching individual fields. Updating a drafted cloud file also publishes it, -applying any `subscriptions` sent with the request. +patching individual fields. Updating a drafted cloud file also publishes it. + +Subscribers are only replaced when you address them: omit both `subscriptions` and +`notify` and a drafted cloud file keeps its current subscribers; send either one to +recompute the list. The creator is always on the list. ###### Example JSON Request diff --git a/sections/documents.md b/sections/documents.md index ce79051..23b4227 100644 --- a/sections/documents.md +++ b/sections/documents.md @@ -231,7 +231,9 @@ Publish a [draft](drafts.md) document by updating it with `status` set to `activ } ``` -A status-only update fails with `400 Bad Request` (the `document` parameters are required), and omitting a field clears its value. Publishing posts the document and notifies its subscribers exactly once — the same publication side-effects as [publishing a message](messages.md#publishing-a-draft). +A status-only update fails with `400 Bad Request` (the `document` parameters are required), and omitting a field clears its value. + +Subscribers are the exception. They're only replaced when you address them: omit both `subscriptions` and `notify` and a drafted document keeps its current subscribers; send either one to recompute the list. The creator and whoever makes the update are always on the list. Publishing posts the document and notifies its subscribers exactly once — the same publication side-effects as [publishing a message](messages.md#publishing-a-draft). Legacy project-scoped routes diff --git a/sections/google_documents.md b/sections/google_documents.md index 6e08d97..68d7850 100644 --- a/sections/google_documents.md +++ b/sections/google_documents.md @@ -225,8 +225,11 @@ Update a Google document Update accepts `title`, `url`, `document_type`, and `description`, and all four are sent on every update — the controller replaces the recordable on each call rather than -patching individual fields. `status` is also accepted; updating a drafted document -applies any `subscriptions` sent with the request. +patching individual fields. `status` is also accepted. + +Subscribers are only replaced when you address them: omit both `subscriptions` and +`notify` and a drafted Google document keeps its current subscribers; send either one +to recompute the list. The creator is always on the list. ###### Example JSON Request diff --git a/sections/messages.md b/sections/messages.md index 8b39c30..beec033 100644 --- a/sections/messages.md +++ b/sections/messages.md @@ -454,6 +454,8 @@ Update a message This endpoint will return `200 OK` with the current JSON representation of the message if the update was a success. See the [Get a message](#get-a-message) endpoint for more info on the payload. +Subscribers are only replaced when you address them: omit both `subscriptions` and `notify` and a drafted message keeps its current subscribers; send either one to recompute the list. The creator and whoever makes the update are always on the list. Note that this differs from [creating a message](#create-a-message), where omitting `subscriptions` subscribes everyone on the project. + ###### Example JSON Request ```json @@ -480,7 +482,7 @@ Publish a [draft](drafts.md) message by updating it with `status` set to `active { "status": "active" } ``` -A message update **merges** the fields you send, so you don't need to resend `subject` or `content` — the draft's existing content is preserved. +A message update **merges** the fields you send, so you don't need to resend `subject` or `content` — the draft's existing content is preserved. The draft's subscribers are preserved too, so publishing notifies the people already on the list unless you send `subscriptions` or `notify` to change it. Publishing is what actually posts the message, and it happens exactly once: each subscriber who should hear about it receives a single notification (delivered shortly after, once notifications are dispatched). Creating or re-saving a draft notifies no one — only publishing does. (Documents publish the same way; see [Publishing a draft](documents.md#publishing-a-draft) in the documents section.) diff --git a/sections/schedule_entries.md b/sections/schedule_entries.md index 5660cc9..c6e2197 100644 --- a/sections/schedule_entries.md +++ b/sections/schedule_entries.md @@ -331,6 +331,8 @@ This endpoint will return `200 OK` with the current JSON representation of the s Participants are only replaced when you address them: omit `participant_ids` and the entry keeps its current participants; send `"participant_ids": []` to remove them all. +Subscribers work the same way, except that participants address them too — a drafted entry's subscribers are derived from its participants. So a draft keeps its current subscribers only when the request omits `subscriptions`, `notify`, **and** the participant parameters; sending any of them recomputes the list, which is what unsubscribes someone you drop from the entry. The creator is always on the list. + ###### Example JSON Request ```json