Skip to content

Remove standalone objects from REST API usage docs #3290

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

Open
VeskeR wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Remove standalone objects from REST API usage docs #3290

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 5 additions & 61 deletions src/pages/docs/liveobjects/rest-api-usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down
Loading