Docs for realtime update/delete, new return type, adding append, and rest api changes for public preview release #3044
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
GregHolmes
left a comment
GregHolmes
left a comment
There was a problem hiding this comment.
Couple small changes needed.
I've added a comment on the Append to a message section as it feels like it's a lot of text that mostly compares appendMessage with updateMessage. Would love to know what you think on that part?
| Unlike `updateMessage()` which replaces the data field, `appendMessage()` concatenates the new data to the existing message's (string or binary) data. This is useful for building up message content incrementally, for example in streaming or gradual message building scenarios. Other fields (`name`, `extras`) will replace the previous values if provided, similar to update mixin semantics. | ||
|
|
||
| The message is identified by its `serial`, which is populated by Ably. To append to a message, you need its serial - you can get this either from the return value of `publish()`, from a received message via subscription, or by querying history. | ||
|
|
||
| When Ably receives an append, we will concatenate the provided data with the current latest version and calculate the updated full (non-incremental) version of the message. That full version of the message is what will be stored in [History](/docs/storage-history/history) as the most recent version, with an action of `message.update`, so someone paging through the history of a channel will never need to do any concatenation themselves, they will just get the full message. Similarly, when attaching to a channel using [rewind](/docs/channels/options/rewind) to get recent messages you will receive only one version of each message, the latest version with the full concatenated data, which means you can specify e.g. `rewind=10` to get the most recent 10 full, distinct messages. Only realtime subscribers receiving live messages will receive the incremental appends (and they can pass a [channel param](/docs/channels/options#append-mode) to request full versions if they want). |
There was a problem hiding this comment.
Could most of this be summarised into a comparison table? It feels like we're comparing the two in these 3 paragraphs creating 4 chunks of text that may be unnecessary?
There was a problem hiding this comment.
I've extracted the bits that are appropriate for an update vs append comparison table - still leaves some prose, but it's a bit more manageable, wdyt?
SimonWoolf
force-pushed
the
protocol-v5
branch
from
156d41c to
9fe1ecf
Compare
NB: not for merging until we do a prod rollout of the serverside components of this change