Update LiveObjects REST API docs for V2 format and improve structure #3119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Merged

zknill merged 3 commits into main from zak/ait-247/rest-api-docs

Jan 22, 2026

Contributor

zknill commented Jan 19, 2026

The LiveObjects REST API moved from V1 (generic "operation" + "data" fields) to V2 (operation-specific fields: mapSet, counterInc, etc.).

Content changes:

Updated the content to match the new V2 API.
Removed the deprecated docs from the open api spec
Added the new V2 api to the open api spec pages.
Added examples of each of the v2 operation types json

Structural improvements:

Reorganized the sections into beginner -> advanced flow.
Added or updated header anchors

Quality fixes:

Standardized field ordering (objectId/path before operation fields)
Reduced some verbosity, and moved some less relevant data lower in the document.

coderabbitai bot commented Jan 19, 2026

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.

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

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

zknill requested review from GregHolmes and mschristensen

January 19, 2026 15:10

Contributor Author

zknill commented Jan 20, 2026

Can only be merged (released) after w/c 19th Jan release has completed.

mschristensen added the review-app label

ably-ci temporarily deployed to ably-docs-zak-ait-247-r-sgjvax

January 21, 2026 14:47

Inactive

Contributor

mschristensen commented Jan 21, 2026

Thanks Zak, we discussed in Slack but sharing my comments here for posterity:

While I appreciate the intention behind introducing simple topics before complex ones, I would prefer to keep related content together in single sections.

As a reader, I want to find everything about a topic (simple to complex) in one place rather than navigating to multiple sections. Readers aren't reading the entire doc top-to-bottom, instead they're using the sidebar to jump to relevant sections, so I think all related information should be findable in one logical place.

However, I agree with the principle of progressive disclosure of complexity, but within the context of individual sections. I think applying this at the document-level makes more sense for "getting started" content or "guides" which have a top-to-bottom narrative flow.

Specific suggestions:

Remove "Getting started" or "Advanced" prefixes in titles, and focus on describing the content that is being documented
"Get objects with metadata" should be part of the "Fetch objects" section
"Advanced path operations" should be part of the "Publishing operations" section
"Client-generated object IDs - we can discuss after other changes are made, but my preference is this should be with "Creating objects" since that's the relevant context where readers would need it
Remove references to "root object" - use "channel object" instead
Add hyperlinks on key terms like LiveMap, instance, etc

ably-ci temporarily deployed to ably-docs-zak-ait-247-r-sgjvax

January 21, 2026 16:56

Inactive

GregHolmes force-pushed the zak/ait-247/rest-api-docs branch from 030b251 to 0a5b328 Compare

January 21, 2026 17:09

GregHolmes temporarily deployed to ably-docs-zak-ait-247-r-sgjvax

January 21, 2026 17:10

Inactive

mschristensen approved these changes

View reviewed changes

Contributor

mschristensen left a comment

Looks great, just misc. small suggestions, approving ahead of that

src/pages/docs/liveobjects/rest-api-usage.mdx Outdated

    
              The key in the `data` object indicates the type of the value:

              | Format | Query parameter | Description |

              |--------|----------------|-------------|

              | **Compact** (default) | None | Logical structure without metadata. Ideal for reading data values. |

Contributor

mschristensen Jan 21, 2026

I'm not sure about the term "logical structure", I'm not sure this is an accurate description. How about something like "values-only representation" or "values-only serialization?

src/pages/docs/liveobjects/rest-api-usage.mdx Outdated

    
              </Code>

              #### Get the entire object with metadata <a id="fetching-object"/>

              This example shows a `LiveMap` "votes" stored on the channel object containing two `LiveCounter` instances: "down" and "up".

Contributor

mschristensen Jan 21, 2026

Suggested change

      
            This example shows a `LiveMap` "votes" stored on the channel object containing two `LiveCounter` instances: "down" and "up".
          
            This example shows a `LiveMap` stored on the "votes" key of the channel object, which contains two `LiveCounter` instances on the "down" and "up" keys.

src/pages/docs/liveobjects/rest-api-usage.mdx Outdated

    
              For example, if you create a cycle in the channel object by adding a reference to the root object in the `votes` `LiveMap` instance with the following operation:

              Each operation includes:

              1. A reference to an object using either **objectId** or **path**

Contributor

mschristensen Jan 21, 2026

Suggested change

      
            1. A reference to an object using either **objectId** or **path**
          
            1. A reference to an object using either `objectId` or `path`

src/pages/docs/liveobjects/rest-api-usage.mdx Outdated

    
              | `mapCreate` | Creates a new LiveMap instance. |

              | `counterCreate` | Creates a new LiveCounter instance. |

              To create an object, see the section on [Creating Objects](#creating-objects).

Contributor

mschristensen Jan 21, 2026

Suggested change

      
            To create an object, see the section on [Creating Objects](#creating-objects).
          
            To create an object, see [Creating Objects](#creating-objects).

src/pages/docs/liveobjects/rest-api-usage.mdx Outdated

    
              To create an object, see the section on [Creating Objects](#creating-objects).

              <Aside data-type='further-reading'>

Contributor

mschristensen Jan 21, 2026

I don't think this belong here, as it applies to the complete API, so I think we should move this to the top

src/pages/docs/liveobjects/rest-api-usage.mdx Outdated

    
              The request body is of the form:

              Optionally omit the `path` or `objectId` fields when creating an object with `mapCreate`.

              For the object to be reachable in the state tree, assign it to a key in a LiveMap that is

              reachable from the root.

Contributor

mschristensen Jan 21, 2026

Suggested change

      
            reachable from the root.
          
            reachable from the channel object.

Contributor

mschristensen Jan 21, 2026

Also, I think we prefer to not introduce our own line breaks in the markdown, instead you can toggle word wrap in your editor if needed

src/pages/docs/liveobjects/rest-api-usage.mdx Outdated

Comment on lines 331 to 332

    
              For the object to be reachable in the state tree, assign it to a key in a LiveMap that is

              reachable from the root.

Contributor

mschristensen Jan 21, 2026

And here

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

    
              For example, given the following compact view of the channel object:

              Paths are expressed relative to the structure of the object as defined by the [compact](#fetch-channel-object) view of the channel object.

              The following example increments the `LiveCounter` instance stored at the `up` key on the `votes` `LiveMap` object:

Contributor

mschristensen Jan 21, 2026 •

edited

Loading

We should review this page to ensure consistent use of backticks/links around LiveMap/LiveCounter

Contributor Author

zknill Jan 22, 2026 •

edited

Loading

I think it might be a bit verbose to be linking every single LiveMap / LiveCounter. They are linked on the occurrences of those terms. But I can check that the backticks are consistent.

src/pages/docs/liveobjects/rest-api-usage.mdx Outdated

    
                    "operation": "MAP_REMOVE",

                    "objectId": "root",

                    "data": {"key": "posts"}

                    "objectId": "map:abc123@ts1",

Contributor

mschristensen Jan 21, 2026

To illustrate this point, can we update the abc123 to reflect the actual hash you would get from the specified nonce and initial value?

src/pages/docs/liveobjects/rest-api-usage.mdx Outdated

    
              ## Object reachability and garbage collection <a id="object-reachability"/>

              Objects must be reachable from the channel object to persist. An object is reachable if it can be accessed by traversing keys starting from the channel object.

Contributor

mschristensen Jan 21, 2026

I think the phrasing "to persist" here might risk incorrect association with persistence i.e. to disk. How about "to avoid being garbage collected" (or perhaps invert the sentence, i.e. "Objects that are not reachable from the channel object will be garbage collected").

ably-ci temporarily deployed to ably-docs-zak-ait-247-r-sgjvax

January 22, 2026 11:06

Inactive

zknill added 3 commits

January 22, 2026 11:07


          Update LiveObjects REST API docs for V2 format and improve structure

c88356a

The LiveObjects REST API moved from V1 (generic "operation" + "data" fields)
to V2 (operation-specific fields: mapSet, counterInc, etc.).

Content changes:
- Updated the content to match the new V2 API.
- Removed the deprecated docs from the open api spec
- Added the new V2 api to the open api spec pages.
- Added examples of each of the v2 operation types json

Structural improvements:
- Reorganized the sections into beginner -> advanced flow.
- Added or updated header anchors

Quality fixes:
- Standardized field ordering (objectId/path before operation fields)
- Reduced some verbosity, and moved some less relevant data lower in the
  document.


          Restructure LiveObjects REST API docs by concept

c521552

- Merge fetch sections into unified "Fetching objects" with format comparison
- Move path operations and removing objects into "Publishing operations"
- Move client-generated IDs into "Creating objects" as subsection
- Replace "root object" with "channel object" in descriptions
- Add cross-links to LiveMap, LiveCounter, PathObject, Instance docs
- Remove "Advanced" prefixes from section headers


          Improve wording and clarity in LiveObjects rest api docs

9d9118b

zknill force-pushed the zak/ait-247/rest-api-docs branch from bf1ce74 to 9d9118b Compare

January 22, 2026 11:07

ably-ci temporarily deployed to ably-docs-zak-ait-247-r-sgjvax

January 22, 2026 11:07

Inactive

zknill merged commit 2ffcdf6 into main

7 checks passed

zknill deleted the zak/ait-247/rest-api-docs branch

January 22, 2026 11:51

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels