[FTF-465] Adds a Product guidance page #3081
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 |
|
|
||
| The Realtime interface is most commonly used client-side. Subscribing to messages is only available through the Realtime interface because it requires establishing a persistent connection to Ably in order to receive messages in realtime. | ||
|
|
||
| ### Comparison |
There was a problem hiding this comment.
Should there also be a mention of cost? Ie maintaining a connection and subscription(s) incurs connection minutes / channel minutes?
| | Typical use | Server-side | Client-side | | ||
| | Connection recovery | Not applicable | Automatic | | ||
|
|
||
| ### When to use each |
There was a problem hiding this comment.
I think this section is mostly duplication
| | Live dashboard | Realtime | | ||
| | Presence and online indicators | Realtime | | ||
| | IoT device sending sensor data | REST or Realtime (depending on frequency) | | ||
| | Backend webhook processing | REST | |
There was a problem hiding this comment.
I'm not sure what "Backend webhook processing" means. Is this something that's handling webhook requests, or making requests?
Also, should there be a mention of what you would use from a cloud function?
| * You need maximum flexibility in message structure and channel design | ||
| * You're building custom realtime features not covered by purpose-built SDKs | ||
| * You need to integrate with existing backend systems | ||
| * Your use case doesn't fit neatly into chat, collaboration, or shared state patterns |
There was a problem hiding this comment.
By referring to shared state here, you're implying that end users would make a choice of using pubsub vs live objects, whereas it is more likely that they'd be using both. There also isn't an SDK choice to be made as there is with chat or spaces.
|
|
||
| [Ably LiveObjects](/docs/liveobjects) provides a simple API for managing shared state that is synchronized in realtime across multiple users or devices. | ||
|
|
||
| Use LiveObjects when you're building: |
There was a problem hiding this comment.
I think here it's perhaps better to characterise this as:
- LiveObjects provides the ability to associate durable state with a channel
- participants can use and modify that state concurrently, with conflicts resolved;
- clients can use that state to hydrate.
Use LiveObjects to manage state when:
- the state is more naturally represented as a structured collection of objects and/or primitive values
- your application needs a way to structure and manage the state explicitly.
Pubsub channels, without LiveObjects, can also be used as a durable store of channel state, and for client hydration, but in this case the state is simply the content of messages sent on the channel. See [history], [rewind] for further discussion of how this pattern applies.
|
|
||
| Use the REST interface of an Ably SDK when: | ||
|
|
||
| * You need REST functionality with additional resilience features |
There was a problem hiding this comment.
I think these two bullets are the same thing
| Use the REST HTTP API directly when: | ||
|
|
||
| * No Ably SDK is available for your platform | ||
| * You have specific resource constraints |
There was a problem hiding this comment.
As above, I would instead express this as "you want to avoid having any third-party SDK in your app or SDK"
|
|
||
| * No Ably SDK is available for your platform | ||
| * You have specific resource constraints | ||
| * You need to make arbitrary API calls that SDKs don't yet support |
There was a problem hiding this comment.
I'm not sure I agree with this point. It's still better to use request() and get the benefit of authentication and fallbacks. So the reason to avoid using an SDK would be one of the other reasons
|
|
||
| Ably recommends using SDK REST interfaces where possible. SDKs provide additional features that improve performance and resilience that the REST HTTP API cannot deliver on its own, such as automatic re-routing around network problems by using alternative datacenters. | ||
|
|
||
| ## Decision flowchart |
There was a problem hiding this comment.
I'm not sure this section adds anything
| * Yes: Use the SDK | ||
| * No: Consider protocol adapters or the REST HTTP API | ||
|
|
||
| ## Combining SDKs for custom features |
There was a problem hiding this comment.
I think this is an important point, and probably should be made earlier. When using a purpose-built SDK, it's still possible, to use those features as well as pubsub features directly, over a shared connection. Do not share the use of specific channels with the purpose-built SDK, but share the connection
…rfaces we'd expect our users to use for their usecase
Description
Adds a Product guidance page which details which products and/or interfaces we'd expect our users to use for their usecase
Checklist