Skip to content

Commit 6162fd0

Browse files
kaschulakaschula
committed
fixup! feat: update LiveObjects usage docs
1 parent a11f2df commit 6162fd0

File tree

2 files changed

+141
-121
lines changed

2 files changed

+141
-121
lines changed

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

Lines changed: 61 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ The key in the `data` object indicates the type of the value:
4343

4444
### Get the entire object <a id="fetching-object-get"/>
4545

46-
The following request returns the entrie object tree.
46+
The following request returns the entire channel object.
4747

4848
<Code>
4949
```shell
@@ -52,27 +52,24 @@ The following request returns the entrie object tree.
5252
```
5353
</Code>
5454

55-
This endpoint by default returns the compact representation of the object tree.
55+
This endpoint returns the compact representation of the channel object.
5656

5757
<Code>
5858
```json
5959
{
60-
"poll": {
61-
"name": "First Poll"
62-
"votes": {
63-
"down": 10,
64-
"up": 5,
65-
}
60+
"votes": {
61+
"down": 10,
62+
"up": 5,
6663
}
6764
}
6865
```
6966
</Code>
7067

71-
#### Get the entire object with metatdata <a id="fetching-object"/>
68+
Each instance of an [object type](/docs/liveobjects/concepts/objects#object-types) included is the response is counted as one billable message.
7269

73-
By providing the `compact=false` query param the response will contain the full object representation including the
74-
objectIds.
70+
#### Get the entire object with metadata <a id="fetching-object"/>
7571

72+
You can optionally include additional object [metadata](/docs/liveobjects/concepts/objects#metadata) in the response by specifying the `compact=false` query option:
7673
<Code>
7774
```shell
7875
curl "https://main.realtime.ably.net/channels/my-channel/object?compact=false" \
@@ -87,43 +84,28 @@ objectIds.
8784
"map": {
8885
"semantics": "LWW",
8986
"entries": {
90-
"poll": {
87+
"votes": {
9188
"data": {
92-
"objectId": "map:fNDMOPlPriqid9SUitqIuP_S-6u5YUYQzxjs39IM68k@1760448542413",
89+
"objectId": "map:qZXBk8xaGqf4kwLSlR7Tj0Eqhd48WDFfb3gTAbj194k@1760448597692",
9390
"map": {
9491
"semantics": "LWW",
9592
"entries": {
96-
"title": {
93+
"down": {
9794
"data": {
98-
"string": "First Poll"
95+
"objectId": "counter:Yj1F_aEX3T2rRkTkra7Aifmlr8PxUWSR3kO3MzxtQto@1760448653393",
96+
"counter": {
97+
"data": {
98+
"number": 5
99+
}
100+
}
99101
}
100102
},
101-
"votes": {
103+
"up": {
102104
"data": {
103-
"objectId": "map:qZXBk8xaGqf4kwLSlR7Tj0Eqhd48WDFfb3gTAbj194k@1760448597692",
104-
"map": {
105-
"semantics": "LWW",
106-
"entries": {
107-
"down": {
108-
"data": {
109-
"objectId": "counter:Yj1F_aEX3T2rRkTkra7Aifmlr8PxUWSR3kO3MzxtQto@1760448653393",
110-
"counter": {
111-
"data": {
112-
"number": 5
113-
}
114-
}
115-
}
116-
},
117-
"up": {
118-
"data": {
119-
"objectId": "counter:ibxddWpDjH8R3cvXWWacfe4IVd3DxT_oqkAafhaS68s@1760448646413",
120-
"counter": {
121-
"data": {
122-
"number": 10
123-
}
124-
}
125-
}
126-
}
105+
"objectId": "counter:ibxddWpDjH8R3cvXWWacfe4IVd3DxT_oqkAafhaS68s@1760448646413",
106+
"counter": {
107+
"data": {
108+
"number": 10
127109
}
128110
}
129111
}
@@ -134,32 +116,27 @@ objectIds.
134116
}
135117
}
136118
}
137-
}
119+
}
120+
138121
```
139122
</Code>
140123

141-
Both these requests are billed per object returned.
142-
143124
#### Get a subset of the object <a id="fetch-object-with-path"/>
144125

145-
You can return a subset of the object tree by specifying the `path` query param. For example, to return just the `poll` `LiveMap` instance from the root object:
126+
You can return a subset of the channel object by specifying the `path` query param. For example, to return just the `votes` `LiveMap` instance from the root object:
146127

147-
// example url
148128
<Code>
149129
```shell
150-
curl "https://main.realtime.ably.net/channels/my-channel/object?path=poll" \
130+
curl "https://main.realtime.ably.net/channels/my-channel/object?path=votes" \
151131
-u {{API_KEY}}
152132
```
153133
</Code>
154134

155135
<Code>
156136
```json
157137
{
158-
"title": "First Poll",
159-
"votes": {
160-
"down": 5,
161-
"up": 10
162-
}
138+
"down": 5,
139+
"up": 10
163140
}
164141
```
165142
</Code>
@@ -174,7 +151,7 @@ To fetch a single object on the channel you can specify the object ID in the URL
174151

175152
<Code>
176153
```shell
177-
curl "https://main.realtime.ably.net/channels/my-channel/object/map:fNDMOPlPriqid9SUitqIuP_S-6u5YUYQzxjs39IM68k@1760448542413" \
154+
curl "https://main.realtime.ably.net/channels/my-channel/object/map:qZXBk8xaGqf4kwLSlR7Tj0Eqhd48WDFfb3gTAbj194k@1760448597692" \
178155
-u {{API_KEY}}
179156
```
180157
</Code>
@@ -185,11 +162,8 @@ full object response.
185162
<Code>
186163
```json
187164
{
188-
"title": "first poll",
189-
"votes": {
190-
"down": 5,
191-
"up": 10
192-
}
165+
"down": 5,
166+
"up": 10
193167
}
194168
```
195169
</Code>
@@ -198,49 +172,34 @@ The full object response can be retrieved by providing the `compact=false` query
198172

199173
<Code>
200174
```shell
201-
curl "https://main.realtime.ably.net/channels/my-channel/object/map:fNDMOPlPriqid9SUitqIuP_S-6u5YUYQzxjs39IM68k@1760448542413?compact=false" \
175+
curl "https://main.realtime.ably.net/channels/my-channel/object/map:qZXBk8xaGqf4kwLSlR7Tj0Eqhd48WDFfb3gTAbj194k@1760448597692?compact=false" \
202176
-u {{API_KEY}}
203177
```
204178
</Code>
205179

206180
<Code>
207181
```json
208182
{
209-
"objectId": "map:fNDMOPlPriqid9SUitqIuP_S-6u5YUYQzxjs39IM68k@1760448542413",
183+
"objectId": "map:qZXBk8xaGqf4kwLSlR7Tj0Eqhd48WDFfb3gTAbj194k@1760448597692",
210184
"map": {
211185
"semantics": "LWW",
212186
"entries": {
213-
"title": {
187+
"down": {
214188
"data": {
215-
"string": "first poll"
189+
"objectId": "counter:Yj1F_aEX3T2rRkTkra7Aifmlr8PxUWSR3kO3MzxtQto@1760448653393",
190+
"counter": {
191+
"data": {
192+
"number": 5
193+
}
194+
}
216195
}
217196
},
218-
"votes": {
197+
"up": {
219198
"data": {
220-
"objectId": "map:qZXBk8xaGqf4kwLSlR7Tj0Eqhd48WDFfb3gTAbj194k@1760448597692",
221-
"map": {
222-
"semantics": "LWW",
223-
"entries": {
224-
"down": {
225-
"data": {
226-
"objectId": "counter:Yj1F_aEX3T2rRkTkra7Aifmlr8PxUWSR3kO3MzxtQto@1760448653393",
227-
"counter": {
228-
"data": {
229-
"number": 5
230-
}
231-
}
232-
}
233-
},
234-
"up": {
235-
"data": {
236-
"objectId": "counter:ibxddWpDjH8R3cvXWWacfe4IVd3DxT_oqkAafhaS68s@1760448646413",
237-
"counter": {
238-
"data": {
239-
"number": 10
240-
}
241-
}
242-
}
243-
}
199+
"objectId": "counter:ibxddWpDjH8R3cvXWWacfe4IVd3DxT_oqkAafhaS68s@1760448646413",
200+
"counter": {
201+
"data": {
202+
"number": 10
244203
}
245204
}
246205
}
@@ -252,11 +211,11 @@ The full object response can be retrieved by providing the `compact=false` query
252211
</Code>
253212

254213

255-
The `path` param can also be provided here to return a subset of the object tree starting from the specified object ID.
214+
The `path` param can also be provided here to return a subset of the channel object starting from the specified object ID.
256215

257216
<Code>
258217
```shell
259-
curl "https://main.realtime.ably.net/channels/my-channel/object/map:fNDMOPlPriqid9SUitqIuP_S-6u5YUYQzxjs39IM68k@1760448542413?path=votes" \
218+
curl "https://main.realtime.ably.net/channels/my-channel/object/map:qZXBk8xaGqf4kwLSlR7Tj0Eqhd48WDFfb3gTAbj194k@1760448597692?path=votes" \
260219
-u {{API_KEY}}
261220
```
262221
</Code>
@@ -275,10 +234,10 @@ The `path` param can also be provided here to return a subset of the object tree
275234

276235
### Cyclic references <a id="fetching-objects-get-cycles"/>
277236

278-
For both the full object and the compact response formats cyclic references in the object tree will be included as a
237+
For both the full object and the compact response formats cyclic references in the channel object will be included as a
279238
reference to the object ID rather than including the same object in the response more than once.
280239

281-
For example, if we created a cycle in the object tree by adding a reference to the root object in the `poll` `LiveMap` instance with the following operation:
240+
For example, if we created a cycle in the channel object by adding a reference to the root object in the `votes` `LiveMap` instance with the following operation:
282241

283242
<Code>
284243
```shell
@@ -287,7 +246,7 @@ For example, if we created a cycle in the object tree by adding a reference to t
287246
-H "Content-Type: application/json" \
288247
-d '{
289248
"operation": "MAP_SET",
290-
"objectId": "map:fNDMOPlPriqid9SUitqIuP_S-6u5YUYQzxjs39IM68k@1760448542413",
249+
"objectId": "map:qZXBk8xaGqf4kwLSlR7Tj0Eqhd48WDFfb3gTAbj194k@1760448597692",
291250
"data": {"key": "myRoot", "value": {"objectId": "root"}}
292251
}'
293252
```
@@ -305,15 +264,12 @@ The response will handle the cyclic reference by including the `myRoot` key in t
305264
<Code>
306265
```json
307266
{
308-
"poll": {
267+
"votes": {
268+
"down": 5,
269+
"up": 10
309270
"myRoot": {
310271
"objectId": "root"
311272
},
312-
"title": "first poll",
313-
"votes": {
314-
"down": 5,
315-
"up": 10
316-
}
317273
}
318274
}
319275
```
@@ -393,13 +349,13 @@ The response includes the ID of the published operation message, the channel and
393349

394350
### Update an object by path <a id="updating-objects-by-path"/>
395351

396-
Path operations provide a convenient way to target objects based on their location in the object tree.
352+
Path operations provide a convenient way to target objects based on their location in the channel object.
397353

398-
Paths are expressed relative to the structure of the object as defined by the [compact](#fetching-objects-compact) view of the object tree.
354+
Paths are expressed relative to the structure of the object as defined by the [compact](#fetching-objects-compact) view of the channel object.
399355

400-
For example, given the following compact view of the object tree:
356+
For example, given the following compact view of the channel object:
401357

402-
The following example increments the `LiveCounter` instance stored at the `up` key on the `votes` `LiveMap` instance on the root object:
358+
The following example increments the `LiveCounter` instance stored at the `up` key on the `votes` `LiveMap` object:
403359

404360
<Code>
405361
```shell
@@ -408,7 +364,7 @@ The following example increments the `LiveCounter` instance stored at the `up` k
408364
-H "Content-Type: application/json" \
409365
-d '{
410366
"operation": "COUNTER_INC",
411-
"path": "poll.votes.up",
367+
"path": "votes.up",
412368
"data": { "number": 1 }
413369
}'
414370
```
@@ -450,7 +406,7 @@ The response includes the IDs of each of the affected object instances:
450406
```
451407
</Code>
452408

453-
Wildcards can be included at the end or in the middle of paths and will match exactly one level in the object tree. For example, given the following compact view of the object tree:
409+
Wildcards can be included at the end or in the middle of paths and will match exactly one level in the channel object. For example, given the following compact view of the channel object:
454410

455411
<Code>
456412
```json
@@ -533,9 +489,9 @@ For `COUNTER_CREATE`, the `data` field should be a JSON object that contains the
533489
```
534490
</Code>
535491

536-
When you create a new object it is important that the new object is assigned to the object tree so that it is [reachable](/docs/liveobjects/concepts/object#reachability) from the root object.
492+
When you create a new object it is important that the new object instance is assigned to the channel object so that it is [reachable](/docs/liveobjects/concepts/object#reachability).
537493

538-
The simplest way to do this is to use the `path` field in the request body. The path is relative to the root object and specifies where in the object tree the new object should be created.
494+
The simplest way to do this is to use the `path` field in the request body. The path is relative to the root object and specifies where in the channel object the new object should be created.
539495

540496
The following example creates a new `LiveMap` instance and assigns it to the `posts` `LiveMap` instance on the root object under the key `post1`:
541497

@@ -574,8 +530,6 @@ The following example shows how to update a key and value in a `LiveMap`:
574530
```
575531
</Code>
576532

577-
Note in this example if the key `title` didn't exist it would have been created and set by this operation.
578-
579533
When using the `path` specifier with a `COUNTER_CREATE` or `MAP_CREATE` operation, the server constructs *two* operations which are published as a [batch](#batch-operations):
580534

581535
* A `MAP_CREATE` or `COUNTER_CREATE` operation used to create the new object

0 commit comments

Comments
 (0)