Skip to content

Commit 59c0052

Browse files
albinsureshalbinsuresh
committed
doc: Entity store query API documentation
1 parent 497e0cb commit 59c0052

File tree

1 file changed

+313
-22
lines changed

1 file changed

+313
-22
lines changed

‎docs/src/operate/registration/register.md

Lines changed: 313 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -85,18 +85,28 @@ GET /v1/entities/{topic-id}
8585
curl http://localhost:8000/tedge/entity-store/v1/entities/device/child01
8686
```
8787

88-
## Query Entities
89-
90-
### Query All Entities
91-
92-
List all entities registered with thin-edge starting from the `main` device.
88+
## Query entities
9389

9490
**Endpoint**
9591

9692
```
9793
GET /v1/entities
9894
```
9995

96+
**Query parameters**
97+
98+
| Parameter | Description | Examples |
99+
|-----------|------------------------------------------------------------------------|-------------------------------------|
100+
| `root` | Entity tree starting from the given `root` node (including it) | `device/child2//` |
101+
| `parent` | Direct child entities of the given `parent` entity (excluding it) | `device/main//` |
102+
| `type` | Entities of the given entity `type` | `main`, `child-device` or `service` |
103+
104+
The following restrictions apply:
105+
* Multiple values can not be specified for the same parameter.
106+
* The same parameter can not be repeated multiple times.
107+
* The `root` and `parent` parameters can not be used together.
108+
109+
100110
**Responses**
101111

102112
* 200: OK
@@ -107,39 +117,320 @@ GET /v1/entities
107117
"@type": "device"
108118
},
109119
{
110-
"@topic-id": "device/main/service/tedge-agent",
120+
"@topic-id": "device/main/service/service0",
111121
"@type": "service",
112122
"@parent": "device/main//"
113123
},
114124
{
115125
"@topic-id": "device/child0//",
116126
"@type": "child-device",
117127
"@parent": "device/main//"
118-
},
119-
{
120-
"@topic-id": "device/child1//",
121-
"@type": "child-device",
122-
"@parent": "device/main//"
123-
},
124-
{
125-
"@topic-id": "device/child00//",
126-
"@type": "child-device",
127-
"@parent": "device/child0//"
128-
},
129-
{
130-
"@topic-id": "device/child01//",
131-
"@type": "child-device",
132-
"@parent": "device/child0//"
133128
}
129+
...
134130
]
135131
```
132+
* 404: Not Found
133+
```
134+
Entity not found with topic id: device/unknown/topic/id
135+
```
136136

137-
**Example**
137+
**Examples**
138+
139+
To demonstrate different query examples, the following entity tree is assumed as the base:
140+
141+
```
142+
main
143+
|-- service0
144+
|-- service1
145+
|-- child0
146+
| |-- child00
147+
| | |-- child000
148+
|-- child1
149+
| |-- service10
150+
|-- child2
151+
| |-- service20
152+
| |-- child20
153+
| | |-- child200
154+
| |-- child21
155+
| | |-- service210
156+
| | |-- child210
157+
| |-- child22
158+
```
159+
160+
### Query all entities
161+
162+
List all entities registered with thin-edge starting from the `main` device at the root.
163+
164+
**Request**
138165

139166
```shell
140167
curl http://localhost:8000/tedge/entity-store/v1/entities
141168
```
142169

170+
**Response**
171+
172+
```json
173+
[
174+
{
175+
"@topic-id": "device/main//",
176+
"@type": "device"
177+
},
178+
{
179+
"@topic-id": "device/main/service/service0",
180+
"@type": "service",
181+
"@parent": "device/main//"
182+
},
183+
{
184+
"@topic-id": "device/main/service/service1",
185+
"@type": "service",
186+
"@parent": "device/main//"
187+
},
188+
{
189+
"@topic-id": "device/child0//",
190+
"@type": "child-device",
191+
"@parent": "device/main//"
192+
},
193+
{
194+
"@topic-id": "device/child1//",
195+
"@type": "child-device",
196+
"@parent": "device/main//"
197+
},
198+
{
199+
"@topic-id": "device/child2//",
200+
"@type": "child-device",
201+
"@parent": "device/main//"
202+
},
203+
{
204+
"@topic-id": "device/child00//",
205+
"@type": "child-device",
206+
"@parent": "device/child0//"
207+
},
208+
{
209+
"@topic-id": "device/child1/service/service10",
210+
"@type": "service",
211+
"@parent": "device/child1//"
212+
},
213+
{
214+
"@topic-id": "device/child2/service/service20",
215+
"@type": "service",
216+
"@parent": "device/child2//"
217+
},
218+
{
219+
"@topic-id": "device/child20//",
220+
"@type": "child-device",
221+
"@parent": "device/child2//"
222+
},
223+
{
224+
"@topic-id": "device/child21//",
225+
"@type": "child-device",
226+
"@parent": "device/child2//"
227+
},
228+
{
229+
"@topic-id": "device/child22//",
230+
"@type": "child-device",
231+
"@parent": "device/child2//"
232+
},
233+
{
234+
"@topic-id": "device/child200//",
235+
"@type": "child-device",
236+
"@parent": "device/child20//"
237+
},
238+
{
239+
"@topic-id": "device/child21/service/service210",
240+
"@type": "service",
241+
"@parent": "device/child21//"
242+
},
243+
{
244+
"@topic-id": "device/child210//",
245+
"@type": "child-device",
246+
"@parent": "device/child21//"
247+
}
248+
]
249+
```
250+
251+
### Query from a root
252+
253+
Query the entity tree from a given root node.
254+
255+
**Request**
256+
257+
```shell
258+
curl http://localhost:8000/tedge/entity-store/v1/entities?root=device/child2//
259+
```
260+
261+
**Response**
262+
263+
```json
264+
[
265+
{
266+
"@topic-id": "device/child2//",
267+
"@type": "child-device",
268+
"@parent": "device/main//"
269+
},
270+
{
271+
"@topic-id": "device/child2/service/service20",
272+
"@type": "service",
273+
"@parent": "device/child2//"
274+
},
275+
{
276+
"@topic-id": "device/child20//",
277+
"@type": "child-device",
278+
"@parent": "device/child2//"
279+
},
280+
{
281+
"@topic-id": "device/child21//",
282+
"@type": "child-device",
283+
"@parent": "device/child2//"
284+
},
285+
{
286+
"@topic-id": "device/child22//",
287+
"@type": "child-device",
288+
"@parent": "device/child2//"
289+
},
290+
{
291+
"@topic-id": "device/child200//",
292+
"@type": "child-device",
293+
"@parent": "device/child20//"
294+
},
295+
{
296+
"@topic-id": "device/child21/service/service210",
297+
"@type": "service",
298+
"@parent": "device/child21//"
299+
},
300+
{
301+
"@topic-id": "device/child210//",
302+
"@type": "child-device",
303+
"@parent": "device/child21//"
304+
}
305+
]
306+
```
307+
308+
### Query by parent
309+
310+
Query only the immediate child entities of a `parent`, excluding any nested entities.
311+
312+
**Request**
313+
314+
```shell
315+
curl http://localhost:8000/tedge/entity-store/v1/entities?parent=device/child2//
316+
```
317+
318+
**Response**
319+
320+
```json
321+
[
322+
{
323+
"@topic-id": "device/child2/service/service20",
324+
"@type": "service",
325+
"@parent": "device/child2//"
326+
},
327+
{
328+
"@topic-id": "device/child20//",
329+
"@type": "child-device",
330+
"@parent": "device/child2//"
331+
},
332+
{
333+
"@topic-id": "device/child21//",
334+
"@type": "child-device",
335+
"@parent": "device/child2//"
336+
},
337+
{
338+
"@topic-id": "device/child22//",
339+
"@type": "child-device",
340+
"@parent": "device/child2//"
341+
}
342+
]
343+
```
344+
345+
### Query by type
346+
347+
Query all entities of type: `child-device`
348+
349+
**Request**
350+
351+
```shell
352+
curl http://localhost:8000/tedge/entity-store/v1/entities?type=child-device
353+
```
354+
355+
**Response**
356+
357+
```json
358+
[
359+
{
360+
"@topic-id": "device/child0//",
361+
"@type": "child-device",
362+
"@parent": "device/main//"
363+
},
364+
{
365+
"@topic-id": "device/child1//",
366+
"@type": "child-device",
367+
"@parent": "device/main//"
368+
},
369+
{
370+
"@topic-id": "device/child2//",
371+
"@type": "child-device",
372+
"@parent": "device/main//"
373+
},
374+
{
375+
"@topic-id": "device/child00//",
376+
"@type": "child-device",
377+
"@parent": "device/child0//"
378+
},
379+
{
380+
"@topic-id": "device/child20//",
381+
"@type": "child-device",
382+
"@parent": "device/child2//"
383+
},
384+
{
385+
"@topic-id": "device/child21//",
386+
"@type": "child-device",
387+
"@parent": "device/child2//"
388+
},
389+
{
390+
"@topic-id": "device/child22//",
391+
"@type": "child-device",
392+
"@parent": "device/child2//"
393+
},
394+
{
395+
"@topic-id": "device/child200//",
396+
"@type": "child-device",
397+
"@parent": "device/child20//"
398+
},
399+
{
400+
"@topic-id": "device/child210//",
401+
"@type": "child-device",
402+
"@parent": "device/child21//"
403+
}
404+
]
405+
```
406+
407+
### Query with multiple parameters
408+
409+
Query all child services of the parent: `device/child2//`.
410+
411+
**Request**
412+
413+
```shell
414+
curl 'http://localhost:8000/tedge/entity-store/v1/entities?parent=device/child2//&type=service'
415+
```
416+
417+
**Response**
418+
419+
```json
420+
[
421+
{
422+
"@topic-id": "device/child2/service/service20",
423+
"@type": "service",
424+
"@parent": "device/child2//"
425+
},
426+
{
427+
"@topic-id": "device/child21/service/service210",
428+
"@type": "service",
429+
"@parent": "device/child21//"
430+
}
431+
]
432+
```
433+
143434
## Delete entity
144435

145436
Deleting an entity results in the deletion of its immediate and nested child entities as well, to avoid leaving orphans behind.

0 commit comments

Comments
 (0)