State Persistence docs

[mattheworiordan]

When we launched last message on channel functionality, it was designed so that developers could persist the last known state of their component/object/app on a channel, and then broadcast those changes out efficiently using Deltas. Conceptually this is a completely different way of using channels, instead of it being a stream of events, a channel now represents the state of an object, and the channel provides a means to distribute updates to subscribers. Examples are you could have a score board, where you publish the complete scoreboard, and all clients subscribe to that with rewind=1 to hydrate the state into their views, and then subscribe for new state updates with deltas enabled to make it binary efficient. This is covered in https://ably.com/blog/from-message-history-to-state-persistence.

However, when you go to our docs on this, https://ably.com/docs/channels/options/rewind?lang=javascript, you can see that the conceptual model has been completely lost. As such, we're not communicating the benefit of why we created this functionality. It is up to us to share the conceptual patterns that we envisage and how customers can use our APIs, instead of just detailing what the API does. What the API does and how it works is really an API reference+, whereas I believe the docs should be talking about concepts and patterns we recommend, and showing people why those patterns are powerful and how to use them.

Note there is a new related ticket to this - see https://ably.atlassian.net/browse/REA-1622. We currently don't support limit=1 for last persisted message functionality via the REST API, and this needs to be fixed.

┆Issue is synchronized with this Jira Task by Unito