[AIT-319] Add LiveObjects REST SDK usage docs by VeskeR · Pull Request #3258 · ably/docs

VeskeR · 2026-03-10T12:01:02Z

Docs for ably/ably-js#2109.

Largely based on the existing usage doc for the REST API [1].
Added REST SDK docs as a separate page for two reasons:

There is no language selector for the shell/curl/HTTP "language", nor
do I think it would look or feel nice UX-wise. It would only exist
for this single page and may not be obvious to readers that they can
switch it at the top to see SDK/API docs.
The SDK docs differ in many minor details throughout, and it would be
a nightmare to maintain different versions on the same page using
if-lang blocks. Where large sections are unchanged (like the
procedure to generate the client-generated object ID), the doc
references the corresponding REST API section instead of duplicating
it.

[1] https://ably.com/docs/liveobjects/rest-api-usage

Resolves AIT-319

Description

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

coderabbitai · 2026-03-10T12:01:22Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: bd66014b-c9e5-4333-b053-5feb6c601681

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch AIT-319/rest-sdk

📝 Coding Plan

Generate coding plan for human review comments

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

CodeRabbit can use Trivy to scan for security misconfigurations and secrets in Infrastructure as Code files.

Add a .trivyignore file to your project to customize which findings Trivy reports.

mschristensen · 2026-03-13T08:29:44Z

Some notes:

Please don't refer to the "channel's root object", it is just the "channel object" since https://ably.atlassian.net/wiki/spaces/LOB/pages/4280811542/LODR-043+Single-object+framing+for+REST+API
Refer to "Non-compact" instead as "Full" e.g. in the table, which matches the name of the type e.g. RestObjectGetFullResult
I don't think we should document creating standalone objects without using them in a batch operation, its a footgun as the object is immediately an orphan
In order to easier for developers to use "Atomic batch with cross-references", I think we should provide a helper method for constructing an object ID given an initial value arg passed like e.g. JSON.stringify()`

Otherwise looks great, thanks

kaschula · 2026-03-13T10:35:30Z

src/pages/docs/liveobjects/rest-sdk-usage.mdx

+
+To use LiveObjects, an API key must have at least the `object-subscribe` capability. With only this capability, clients will have read-only access, preventing them from publishing operations.
+
+In order to create or update objects, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/auth/capabilities) to allow full read and write access.


This reads like you need object-subscribe to publish messages. Perhaps it should be something like

In order to create or update objects, make sure your API key includes the `object-publish` [capability](/docs/auth/capabilities). For full read and write access include both.

Or

To allow full read and write access include both the `object-subscribe` and `object-publish` [capabilities](/docs/auth/capabilities).

Was copied from the REST API usage docs, updated both to be clear about the expected capability string, see 6fda2c3

kaschula · 2026-03-13T10:38:01Z

src/pages/docs/liveobjects/rest-sdk-usage.mdx

+
+`get(RestObjectGetParams params?): Promise<Object>`
+
+Reads object data from the channel. Uses the channel's root object as the entrypoint when no `objectId` is provided. Makes a request to the [`GET /channels/{channelId}/object`](/docs/liveobjects/rest-api-usage#fetch-channel-object) REST API endpoint. The return type depends on the `compact` parameter: when `compact` is `true` (default), returns a [`RestObjectGetCompactResult`](#rest-object-get-compact-result); when `compact` is `false`, returns a [`RestObjectGetFullResult`](#rest-object-get-full-result).


I think Uses the channel's root object should be Uses the channel object

Maybe this sentence should:

Reads object data from the channel. If no `objectId` is provided then the entire channel object is retruned.

Same as Mike's comment about not using "root". Fixed in 6fda2c3

kaschula

A few comments, nothing major

lawrence-forooghian · 2026-03-13T17:41:52Z

src/pages/docs/liveobjects/rest-sdk-usage.mdx

+| **Compact** (default) | `compact: true` | Values-only representation without metadata. Ideal for reading data values. |
+| **Non-compact** | `compact: false` | Full structure including object IDs and type metadata. Useful for debugging. |
+
+**Compact format** returns the logical structure of your data as a JSON-like value. [LiveMap](/docs/liveobjects/map) instances appear as JSON objects with their entries, and [LiveCounter](/docs/liveobjects/counter) instances appear as numbers. `bytes`-typed values are returned as <If lang="javascript">`ArrayBuffer`</If><If lang="nodejs">`Buffer`</If> when using the binary protocol, or as base64-encoded strings when using the JSON protocol. `json`-typed values remain as their JSON-encoded string representation, as the client SDK cannot distinguish between a regular string and a JSON-encoded string in the compact view.


json-typed values remain as their JSON-encoded string representation, as the client SDK cannot distinguish between a regular string and a JSON-encoded string in the compact view

I'm not sure what this sentence is trying to express — is it "this is a restriction imposed on the SDK by the design of the REST API"? Because the REST API could conceivably return json values as inline JSON values, but chooses not to (for reasons I don't understand but which have presumably been discussed).

I'm not sure what this sentence is trying to express — is it "this is a restriction imposed on the SDK by the design of the REST API"?

Yes, would you like it to be removed and just be "json-typed values remain as their JSON-encoded string representation"?

Decided to remove "as the client SDK cannot distinguish between a regular string and a JSON-encoded string in the compact view" and similar line from "Data values reference" section in 6fda2c3

lawrence-forooghian · 2026-03-13T17:46:15Z

src/pages/docs/liveobjects/rest-sdk-usage.mdx

+</Aside>
+
+<Aside data-type='further-reading'>
+See [PathObject](/docs/liveobjects/concepts/path-object) for details on path-based access in client SDKs.


The current page arguably already describes "path-based access in client SDKs" (i.e. the REST interface of the SDK); should it say in "realtime client SDKs"?

Updated both REST API and new REST SDK docs in 6fda2c3 to say "realtime client SDKs"

lawrence-forooghian · 2026-03-13T18:39:15Z

src/pages/docs/liveobjects/rest-sdk-usage.mdx

+
+## Related types <a id="related-types"/>
+
+### RestObjectGetParams <a id="rest-object-get-params"/>


I was struggling to understand the heading hierarchy here — here's what Claude thinks:

- ### RestObjectGetCompactResult (h3) - ### RestObjectGetFullResult (h3) - ### RestLiveObject (h3) - #### RestLiveMap (h4) ✓ - #### RestLiveMapValue (h4) — should be h5? It's a child of RestLiveMap - ### RestObjectDataMapEntry (h3) — should be h4 or h5, it's nested under RestLiveMapValue - #### RestLiveObjectMapEntry (h4) — peer of RestObjectDataMapEntry but at a different heading level - #### RestLiveCounter (h4) — peer of RestLiveMap, this is correct - #### RestLiveCounterValue (h4) — child of RestLiveCounter, should be h5 - ### RestObjectData (h3) - ### PublishObjectData (h3) - ### RestObjectPublishResult (h3)

also the sidebar doesn't reflect the hierarchy — does it stop indenting further after a certain heading level?

also the sidebar doesn't reflect the hierarchy — does it stop indenting further after a certain heading level?

It seems to be intended behavior of the docs website (I assume to avoid overloading the nav). It only renders two levels: ** and ***. Any other headings are only on the page itself.

I was struggling to understand the heading hierarchy here — here's what Claude thinks:

I think I added those additional headings for some types by mistake. They should all sit at the same ### level, as we're just listing all related types used by the REST SDK methods. I've changed all types to use the same ### heading in 6fda2c3 - this is consistent with other REST SDK docs, like at https://ably.com/docs/api/rest-sdk/types#rest-data-types

mschristensen · 2026-03-17T15:33:54Z

I dont think this comment has been addressed:

I don't think we should document creating standalone objects without using them in a batch operation, its a footgun as the object is immediately an orphan

Applies suggestions from REST SDK usage docs PR [1] [1] ably/docs#3258 (comment)

As suggested in REST SDK usage docs PR [1], provide a helper for generating object IDs needed for *CreateWithObjectId operations. Constructing IDs manually is error-prone, and the SDK already has the internal machinery for this (used by the realtime client), so exposing it as a public method is straightforward. [1] ably/docs#3258 (comment)

… IDs As suggested in [1] the REST SDK now exposes a generateObjectId() method that handles the ID generation internally, removing the need for developers to manually hash initial values and nonces. Update the client-generated IDs section to use this helper and add the related types. See ably-js implementation in [2] for reference. [1] #3258 (comment) [2] ably/ably-js@2d973c6

Largely based on the existing usage doc for the REST API [1]. Added REST SDK docs as a separate page for two reasons: 1. There is no language selector for the shell/curl/HTTP "language", nor do I think it would look or feel nice UX-wise. It would only exist for this single page and may not be obvious to readers that they can switch it at the top to see SDK/API docs. 2. The SDK docs differ in many minor details throughout, and it would be a nightmare to maintain different versions on the same page using if-lang blocks. Where large sections are unchanged (like the procedure to generate the client-generated object ID), the doc references the corresponding REST API section instead of duplicating it. Resolves AIT-319 [1] https://ably.com/docs/liveobjects/rest-api-usage

… IDs As suggested in [1] the REST SDK now exposes a generateObjectId() method that handles the ID generation internally, removing the need for developers to manually hash initial values and nonces. Update the client-generated IDs section to use this helper and add the related types. See ably-js implementation in [2] for reference. [1] #3258 (comment) [2] ably/ably-js@2d973c6

VeskeR · 2026-03-17T16:47:03Z

@mschristensen

Please don't refer to the "channel's root object", it is just the "channel object" since https://ably.atlassian.net/wiki/spaces/LOB/pages/4280811542/LODR-043+Single-object+framing+for+REST+API

REST SDK docs were based on the existing "REST API usage", which still used the term "root" in some places. I've fixed both (REST SDK and REST API docs) to now only use "channel object" in 6fda2c3.

Refer to "Non-compact" instead as "Full" e.g. in the table, which matches the name of the type e.g. RestObjectGetFullResult

Changed in 6fda2c3. Also updated REST API usage docs to use "Full" to keep it consistent between the two.

I don't think we should document creating standalone objects without using them in a batch operation, its a footgun as the object is immediately an orphan

I've removed that section from the REST SDK docs and made it clear that in the "client-generated ids" flow users should assign in the same batch. See 6fda2c3.

Question: REST API docs have the same section for standalone objects. Would you like it to be removed for REST API docs too?

In order to easier for developers to use "Atomic batch with cross-references", I think we should provide a helper method for constructing an object ID given an initial value arg passed like e.g. JSON.stringify()`

I've added a new RestObject.generateObjectId helper to the ably-js imlementation in ably/ably-js@2d973c6, and updated the docs to use that helper instead of suggesting to create an object ID manually, see 65f2a71

VeskeR requested review from GregHolmes, lawrence-forooghian and mschristensen March 10, 2026 12:01

VeskeR added the review-app Create a Heroku review app label Mar 10, 2026

ably-ci temporarily deployed to ably-docs-ait-319-rest--qd9urv March 10, 2026 12:31 Inactive

VeskeR force-pushed the AIT-319/rest-sdk branch from f08cbfb to 2ac8d6a Compare March 10, 2026 14:16

ably-ci temporarily deployed to ably-docs-ait-319-rest--qd9urv March 10, 2026 14:17 Inactive

VeskeR force-pushed the AIT-319/rest-sdk branch from 2ac8d6a to 72f0c85 Compare March 11, 2026 06:59

ably-ci temporarily deployed to ably-docs-ait-319-rest--qd9urv March 11, 2026 06:59 Inactive

VeskeR force-pushed the AIT-319/rest-sdk branch from 72f0c85 to f53ddb4 Compare March 11, 2026 08:07

ably-ci temporarily deployed to ably-docs-ait-319-rest--qd9urv March 11, 2026 08:08 Inactive

VeskeR force-pushed the AIT-319/rest-sdk branch from f53ddb4 to a010f31 Compare March 11, 2026 22:11

ably-ci temporarily deployed to ably-docs-ait-319-rest--qd9urv March 11, 2026 22:11 Inactive

VeskeR requested a review from kaschula March 12, 2026 12:10

VeskeR force-pushed the AIT-319/rest-sdk branch from a010f31 to 4ed0150 Compare March 12, 2026 17:31

ably-ci temporarily deployed to ably-docs-ait-319-rest--qd9urv March 12, 2026 17:31 Inactive

kaschula reviewed Mar 13, 2026

View reviewed changes

VeskeR mentioned this pull request Mar 13, 2026

[AIT-27, PUB-1197] LiveObjects REST client ably/ably-js#2109

Open

lawrence-forooghian reviewed Mar 13, 2026

View reviewed changes

VeskeR added a commit to ably/ably-js that referenced this pull request Mar 17, 2026

Refer to "non-compact" as "full" and don't use "channel root" term

8d25ece

Applies suggestions from REST SDK usage docs PR [1] [1] ably/docs#3258 (comment)

ably-ci temporarily deployed to ably-docs-ait-319-rest--qd9urv March 17, 2026 16:37 Inactive

VeskeR added 3 commits March 17, 2026 16:38

fixup: address feedback

6fda2c3

VeskeR force-pushed the AIT-319/rest-sdk branch from a7b931b to 65f2a71 Compare March 17, 2026 16:38

ably-ci deployed to ably-docs-ait-319-rest--qd9urv March 17, 2026 16:38 View deployment

VeskeR requested review from kaschula and lawrence-forooghian March 17, 2026 16:56


		To use LiveObjects, an API key must have at least the `object-subscribe` capability. With only this capability, clients will have read-only access, preventing them from publishing operations.

		In order to create or update objects, make sure your API key includes both `object-subscribe` and `object-publish` [capabilities](/docs/auth/capabilities) to allow full read and write access.


		`get(RestObjectGetParams params?): Promise<Object>`

		Reads object data from the channel. Uses the channel's root object as the entrypoint when no `objectId` is provided. Makes a request to the [`GET /channels/{channelId}/object`](/docs/liveobjects/rest-api-usage#fetch-channel-object) REST API endpoint. The return type depends on the `compact` parameter: when `compact` is `true` (default), returns a [`RestObjectGetCompactResult`](#rest-object-get-compact-result); when `compact` is `false`, returns a [`RestObjectGetFullResult`](#rest-object-get-full-result).


		## Related types <a id="related-types"/>

		### RestObjectGetParams <a id="rest-object-get-params"/>

Conversation

VeskeR commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

coderabbitai bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

mschristensen commented Mar 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kaschula left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

VeskeR Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

VeskeR Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mschristensen commented Mar 17, 2026

Uh oh!

VeskeR commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

5 participants

VeskeR commented Mar 10, 2026 •

edited

Loading

coderabbitai bot commented Mar 10, 2026 •

edited

Loading

VeskeR Mar 17, 2026 •

edited

Loading

VeskeR Mar 17, 2026 •

edited

Loading

VeskeR commented Mar 17, 2026 •

edited

Loading