[AIT-319] Add LiveObjects REST SDK usage docs

[VeskeR]

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:

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.

[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]

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: 363aeb2f-b425-4458-956e-474d36bf847c

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
• Post copyable unit tests in a comment
• 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

• X
• Mastodon
• Reddit
• LinkedIn

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

Tip

You can generate walkthrough in a markdown collapsible section to save space.

Enable the reviews.collapse_walkthrough setting to generate walkthrough in a markdown collapsible section.

[mschristensen]

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]

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).

[kaschula]

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.

[kaschula]

A few comments, nothing major

[lawrence-forooghian]

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).

[lawrence-forooghian]

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"?

[lawrence-forooghian]

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)

[lawrence-forooghian]

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