From 2b943e2419ec041f4d7482495829ab973e0852cf Mon Sep 17 00:00:00 2001
From: Andrew Bulat <andrii.bulat@gmail.com>
Date: Thu, 19 Mar 2026 15:45:10 +0000
Subject: [PATCH] Remove standalone objects from REST API usage docs

Standalone object creation is not a pattern we want to encourage,
as objects not assigned to the object tree are immediately
unreachable and subject to garbage collection. This mirrors the
same change made to the REST SDK usage docs in 3ddb9d623586723a462bb5ddb500bed55bcdc6e1,
as a result of the PR comment [1].

Remove the "Creating standalone objects" section and the
"Publishing with client-generated IDs" subsection (which showed
creating a standalone object). The client-generated IDs section
now only shows the atomic batch example that creates and assigns
in one operation, with an important note that objects should be
assigned to the tree as part of the same batch.

[1] https://github.com/ably/docs/pull/3258#issuecomment-4053558952
---
 src/pages/docs/liveobjects/rest-api-usage.mdx | 66 ++-----------------
 1 file changed, 5 insertions(+), 61 deletions(-)

diff --git a/src/pages/docs/liveobjects/rest-api-usage.mdx b/src/pages/docs/liveobjects/rest-api-usage.mdx
index cb098b250b..5e2e58d043 100644
--- a/src/pages/docs/liveobjects/rest-api-usage.mdx
+++ b/src/pages/docs/liveobjects/rest-api-usage.mdx
@@ -562,42 +562,6 @@ The newly created object's ID will be the first item in the list:
 ```
 </Code>
 
-### Creating standalone objects <a id="creating-standalone"/>
-
-Create objects without immediately assigning them by omitting both `objectId` and `path` from the create operation.
-
-<Code>
-```shell
-  curl -X POST "https://main.realtime.ably.net/channels/my-channel/object" \
-    -u {{API_KEY}} \
-    -H "Content-Type: application/json" \
-    -d '{
-      "mapCreate": {
-        "semantics": 0,
-        "entries": {
-          "name": {"data": {"string": "Alice"}}
-        }
-      }
-    }'
-```
-</Code>
-
-The response includes the generated object ID:
-
-<Code>
-```json
-{
-  "messageId": "TJPWHhMTrF:0",
-  "channel": "my-channel",
-  "objectIds": ["map:abc123def456...@1745835549101"]
-}
-```
-</Code>
-
-<Aside data-type='important'>
-Standalone objects are not reachable until assigned to the object tree. Unreachable objects are eligible for garbage collection. See [Object reachability and garbage collection](#object-reachability) for details.
-</Aside>
-
 ### Client-generated object IDs <a id="client-generated-ids"/>
 
 Generate [object IDs](/docs/liveobjects/concepts/objects#object-ids) when creating objects to enable atomic batch operations with cross-references between newly created objects. This is useful when creating multiple objects that reference each other in a single batch.
@@ -660,31 +624,7 @@ There are additional operations for creating objects with client-generated IDs:
 The server validates that your `objectId` matches the hash of `initialValue + nonce`.
 </Aside>
 
-#### Publishing with client-generated IDs <a id="creating-with-client-ids"/>
-
-Publish an operation using either `mapCreateWithObjectId` or `counterCreateWithObjectId` to create
-an object with a client-generated ID.
-
-For example:
-
-<Code>
-```shell
-  curl -X POST "https://main.realtime.ably.net/channels/my-channel/object" \
-    -u {{API_KEY}} \
-    -H "Content-Type: application/json" \
-    -d '{
-      "objectId": "map:Qj2kkvprTybCY5mkNMcm31hhNKZCDWqcz45LjYvCABs@1769079911168",
-      "mapCreateWithObjectId": {
-        "initialValue": "{\"semantics\":0,\"entries\":{\"name\":{\"data\":{\"string\":\"Alice\"}},\"age\":{\"data\":{\"number\":30}}}}",
-        "nonce": "random-nonce-abc123"
-      }
-    }'
-```
-</Code>
-
-#### Atomic batch with cross-references <a id="atomic-batch-cross-references"/>
-
-Create a map and immediately assign it to the channel object in a single atomic operation:
+The following example creates a new `LiveMap` instance with a pre-computed object ID using the `mapCreateWithObjectId` operation, and immediately assigns it to the channel object in a single atomic batch:
 
 <Code>
 ```shell
@@ -712,6 +652,10 @@ Create a map and immediately assign it to the channel object in a single atomic
 
 Both operations execute atomically. The second operation references the object created in the first because you pre-computed the ID.
 
+<Aside data-type='important'>
+Objects created with client-generated IDs should be assigned to the object tree as part of the same batch operation. Objects that are not assigned are immediately unreachable and subject to [garbage collection](#object-reachability).
+</Aside>
+
 <Aside data-type='note'>
 Only use client-generated IDs when you need atomic batch operations with cross-references. For most use cases, use simple operations or path-based operations instead.
 </Aside>