Skip to content

Commit e974546

Browse files
author
Ricardo Cañuelo
committed
doc/api-details: update Node examples, model format and operators
Sync the docs to the current model definitions and mention the `__re` operator, including an example. Signed-off-by: Ricardo Cañuelo <[email protected]>
1 parent 8e6a806 commit e974546

File tree

1 file changed

+258
-28
lines changed

1 file changed

+258
-28
lines changed

‎doc/api-details.md

+258-28
Original file line numberDiff line numberDiff line change
@@ -82,13 +82,18 @@ Another way of creating users is to use `kci user add` tool from kernelci-core.
8282

8383
## Nodes
8484

85-
As a proof-of-concept, an object model called `Node` is defined in this API.
86-
It's possible to create new objects and retrieve them via the API.
85+
`Node` objects form the basis of the API models to represent tests runs,
86+
kernel builds, regressions and other test-related entities and their
87+
relationships. See [the model definitions in
88+
kernelci-core](https://github.com/kernelci/kernelci-core/blob/main/kernelci/api/models.py)
89+
for details on the `Node` model and its subtypes. It's possible to
90+
create new objects and retrieve them via the API.
8791

8892
### Create a Node
8993

90-
To create an object of `Node` model, a `POST` request should be made along with
91-
the Node attributes. This requires an authentication token:
94+
To create a `Node` or a `Node` subtype object, for instance, a
95+
`Checkout` node, a `POST` request should be made along with the Node
96+
attributes. This requires an authentication token:
9297

9398
```
9499
$ curl -X 'POST' \
@@ -97,14 +102,48 @@ $ curl -X 'POST' \
97102
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJib2IifQ.ci1smeJeuX779PptTkuaG1SEdkp5M1S1AgYvX8VdB20' \
98103
-H 'Content-Type: application/json' \
99104
-d '{
100-
"name":"checkout",
101-
"revision":{"tree":"mainline",
102-
"url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
103-
"branch":"master",
104-
"commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26",
105-
"describe":"v5.16-rc4-31-g2a987e65025e"}
106-
}'
107-
{"_id":"61bda8f2eb1a63d2b7152418","kind":"node","name":"checkout","revision":{"tree":"mainline","url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git","branch":"master","commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26","describe":"v5.16-rc4-31-g2a987e65025e"},"parent":null,"status":"pending","result":null, "created":"2022-02-02T11:23:03.157648", "updated":"2022-02-02T11:23:03.157648"}
105+
"name": "checkout",
106+
"kind": "checkout",
107+
"path": ["checkout"],
108+
"data": {
109+
"kernel_revision": {
110+
"tree": "mainline",
111+
"url": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
112+
"branch": "master",
113+
"commit": "2a987e65025e2b79c6d453b78cb5985ac6e5eb26",
114+
"describe": "v5.16-rc4-31-g2a987e65025e"
115+
}
116+
}
117+
}' | jq
118+
119+
{
120+
"id": "61bda8f2eb1a63d2b7152418",
121+
"kind": "checkout",
122+
"name": "checkout",
123+
"path": [
124+
"checkout"
125+
],
126+
"group": null,
127+
"parent": null,
128+
"state": "running",
129+
"result": null,
130+
"artifacts": null,
131+
"data": {
132+
"kernel_revision": {
133+
"tree": "mainline",
134+
"url": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
135+
"branch": "master",
136+
"commit": "2a987e65025e2b79c6d453b78cb5985ac6e5eb26",
137+
"describe": "v5.16-rc4-31-g2a987e65025e"
138+
}
139+
},
140+
"created": "2024-02-01T09:58:28.479138",
141+
"updated": "2024-02-01T09:58:28.479142",
142+
"timeout": "2024-02-01T15:58:28.479145",
143+
"holdoff": null,
144+
"owner": "admin",
145+
"user_groups": []
146+
}
108147
```
109148

110149
### Getting Nodes back
@@ -114,42 +153,229 @@ Reading Node doesn't require authentication, so plain URLs can be used.
114153
To get node by ID, use `/node` endpoint with node ID as a path parameter:
115154

116155
```
117-
$ curl http://localhost:8001/latest/node/61bda8f2eb1a63d2b7152418
118-
{"_id":"61bda8f2eb1a63d2b7152418","kind":"node","name":"checkout","revision":{"tree":"mainline","url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git","branch":"master","commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26","describe":"v5.16-rc4-31-g2a987e65025e"},"parent":null,"status":"pending","result":null, "created":"2022-02-02T11:23:03.157648", "updated":"2022-02-02T11:23:03.157648"}
156+
$ curl http://localhost:8001/latest/node/61bda8f2eb1a63d2b7152418 | jq
157+
158+
{
159+
"id": "61bda8f2eb1a63d2b7152418",
160+
"kind": "checkout",
161+
"name": "checkout",
162+
"path": [
163+
"checkout"
164+
],
165+
"group": null,
166+
"parent": null,
167+
"state": "running",
168+
"result": null,
169+
"artifacts": null,
170+
"data": {
171+
"kernel_revision": {
172+
"tree": "mainline",
173+
"url": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
174+
"branch": "master",
175+
"commit": "2a987e65025e2b79c6d453b78cb5985ac6e5eb26",
176+
"describe": "v5.16-rc4-31-g2a987e65025e"
177+
}
178+
},
179+
"created": "2024-02-01T09:58:28.479000",
180+
"updated": "2024-02-01T09:58:28.479000",
181+
"timeout": "2024-02-01T15:58:28.479000",
182+
"holdoff": null,
183+
"owner": "admin",
184+
"user_groups": []
185+
}
119186
```
120187

121188
To get all the nodes as a list, use the `/nodes` API endpoint:
122189

123190
```
124191
$ curl http://localhost:8001/latest/nodes
125-
[{"_id":"61b052199bca2a448fe49673","kind":"node","name":"checkout","revision":{"tree":"mainline","url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git","branch":"master","commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26","describe":"v5.16-rc4-31-g2a987e65025e"},"parent":null,"status":"pending","result":null, "created":"2022-02-01T11:23:03.157648", "updated":"2022-02-02T11:23:03.157648"},{"_id":"61b052199bca2a448fe49674","kind":"node","name":"check-describe","revision":{"tree":"mainline","url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git","branch":"master","commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26","describe":"v5.16-rc4-31-g2a987e65025e"},"parent":"61b052199bca2a448fe49673","status":"pending", "result":null,"created":"2022-01-02T10:23:03.157648", "updated":"2022-01-02T11:23:03.157648"}]
192+
{
193+
"items": [
194+
{
195+
"id": "65a1355ee98651d0fe81e412",
196+
"kind": "node",
197+
"name": "time_test_cases",
198+
"path": [
199+
"checkout",
200+
"kunit-x86_64",
201+
"exec",
202+
"time_test_cases"
203+
],
204+
"group": "kunit-x86_64",
205+
"parent": "65a1355ee98651d0fe81e40f",
206+
"state": "done",
207+
"result": null,
208+
"artifacts": null,
209+
"data": {
210+
"kernel_revision": {
211+
"tree": "mainline",
212+
"url": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
213+
"branch": "master",
214+
"commit": "70d201a40823acba23899342d62bc2644051ad2e",
215+
"describe": "v6.7-6264-g70d201a40823",
216+
"version": {
217+
"version": "6",
218+
"patchlevel": "7",
219+
"extra": "-6264-g70d201a40823"
220+
}
221+
}
222+
},
223+
"created": "2024-01-12T12:49:33.996000",
224+
"updated": "2024-01-12T12:49:33.996000",
225+
"timeout": "2024-01-12T18:49:33.996000",
226+
"holdoff": null,
227+
"owner": "admin",
228+
"user_groups": []
229+
},
230+
{
231+
"id": "65a1355ee98651d0fe81e413",
232+
"kind": "node",
233+
"name": "time64_to_tm_test_date_range",
234+
"path": [
235+
"checkout",
236+
"kunit-x86_64",
237+
"exec",
238+
"time_test_cases",
239+
"time64_to_tm_test_date_range"
240+
],
241+
"group": "kunit-x86_64",
242+
"parent": "65a1355ee98651d0fe81e412",
243+
"state": "done",
244+
"result": "pass",
245+
"artifacts": null,
246+
"data": {
247+
"kernel_revision": {
248+
"tree": "mainline",
249+
"url": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
250+
"branch": "master",
251+
"commit": "70d201a40823acba23899342d62bc2644051ad2e",
252+
"describe": "v6.7-6264-g70d201a40823",
253+
"version": {
254+
"version": "6",
255+
"patchlevel": "7",
256+
"extra": "-6264-g70d201a40823"
257+
}
258+
}
259+
},
260+
"created": "2024-01-12T12:49:33.996000",
261+
"updated": "2024-01-12T12:49:33.996000",
262+
"timeout": "2024-01-12T18:49:33.996000",
263+
"holdoff": null,
264+
"owner": "admin",
265+
"user_groups": []
266+
},
267+
...
126268
```
127269

128270
To get nodes by providing attributes, use `/nodes` endpoint with query
129271
parameters. All the attributes except node ID can be passed to this endpoint.
130272
In case of ID, please use `/node` endpoint with node ID as described above.
131273

132274
```
133-
$ curl 'http://localhost:8001/latest/nodes?name=checkout&revision.tree=mainline'
134-
[{"_id":"61b052199bca2a448fe49673","kind":"node","name":"checkout","revision":{"tree":"mainline","url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git","branch":"master","commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26","describe":"v5.16-rc4-31-g2a987e65025e"},"parent":null,"status":"pending","result":null, "created":"2022-02-01T11:23:03.157648", "updated":"2022-02-02T11:23:03.157648"}]
275+
$ curl 'http://localhost:8001/latest/nodes?kind=checkout&data.kernel_revision.tree=mainline' | jq
276+
277+
{
278+
"items": [
279+
{
280+
"id": "65a3982ee98651d0fe82b010",
281+
"kind": "checkout",
282+
"name": "checkout",
283+
"path": [
284+
"checkout"
285+
],
286+
"group": null,
287+
"parent": null,
288+
"state": "done",
289+
"result": null,
290+
"artifacts": {
291+
"tarball": "https://kciapistagingstorage1.file.core.windows.net/staging/linux-mainline-master-v6.7-9928-g052d534373b7.tar.gz?sv=2022-11-02&ss=f&srt=sco&sp=r&se=2024-10-17T19:19:12Z&st=2023-10-17T11:19:12Z&spr=https&sig=sLmFlvZHXRrZsSGubsDUIvTiv%2BtzgDq6vALfkrtWnv8%3D"
292+
},
293+
"data": {
294+
"kernel_revision": {
295+
"tree": "mainline",
296+
"url": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
297+
"branch": "master",
298+
"commit": "052d534373b7ed33712a63d5e17b2b6cdbce84fd",
299+
"describe": "v6.7-9928-g052d534373b7",
300+
"version": {
301+
"version": "6",
302+
"patchlevel": "7",
303+
"extra": "-9928-g052d534373b7"
304+
}
305+
}
306+
},
307+
"created": "2024-01-14T08:15:42.454000",
308+
"updated": "2024-01-14T09:16:47.689000",
309+
"timeout": "2024-01-14T09:15:42.344000",
310+
"holdoff": "2024-01-14T08:46:39.040000",
311+
"owner": "admin",
312+
"user_groups": []
313+
},
314+
{
315+
"id": "65a3a545e98651d0fe82b4ed",
316+
"kind": "checkout",
317+
"name": "checkout",
318+
"path": [
319+
"checkout"
320+
],
321+
"group": null,
322+
"parent": null,
323+
"state": "done",
324+
"result": null,
325+
"artifacts": {
326+
"tarball": "https://kciapistagingstorage1.file.core.windows.net/staging/linux-mainline-master-v6.7-9928-g052d534373b7.tar.gz?sv=2022-11-02&ss=f&srt=sco&sp=r&se=2024-10-17T19:19:12Z&st=2023-10-17T11:19:12Z&spr=https&sig=sLmFlvZHXRrZsSGubsDUIvTiv%2BtzgDq6vALfkrtWnv8%3D"
327+
},
328+
"data": {
329+
"kernel_revision": {
330+
"tree": "mainline",
331+
"url": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
332+
"branch": "master",
333+
"commit": "052d534373b7ed33712a63d5e17b2b6cdbce84fd",
334+
"describe": "v6.7-9928-g052d534373b7",
335+
"version": {
336+
"version": "6",
337+
"patchlevel": "7",
338+
"extra": "-9928-g052d534373b7"
339+
}
340+
}
341+
},
342+
"created": "2024-01-14T09:11:33.029000",
343+
"updated": "2024-01-14T10:11:48.092000",
344+
"timeout": "2024-01-14T10:11:32.922000",
345+
"holdoff": "2024-01-14T09:40:19.284000",
346+
"owner": "admin",
347+
"user_groups": []
348+
}
349+
...
135350
```
136351

137352
Attributes along with comparison operators are also supported for the
138-
`/nodes` endpoint. The attribute name and operator should be separated by `__` i.e. `attribute__operator`. Supported operators are `lt`(less than), `gt`(greater than), `lte`(less than or equal to), and `gte`(greater than or equal to).
353+
`/nodes` endpoint. The attribute name and operator should be separated
354+
by `__` i.e. `attribute__operator`. Supported operators are `lt`(less
355+
than), `gt`(greater than), `lte`(less than or equal to), `gte`(greater
356+
than or equal to) and `re` (regular expression matching).
139357

140358
```
141-
$ curl 'http://localhost:8001/latest/nodes?name=checkout&created__gt=2022-12-06T04:59:08.102000'
142-
{"items":[{"_id":"638ecc1c749a8d1209b758af","kind":"node","name":"checkout","path":["checkout"],"group":null,"revision":{"tree":"mainline","url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git","branch":"master","commit":"bce9332220bd677d83b19d21502776ad555a0e73","describe":"v6.1-rc8-3-gbce9332220bd","version":{"version":6,"patchlevel":1,"sublevel":null,"extra":"-rc8-3-gbce9332220bd","name":null}},"parent":null,"state":"done","result":"pass","artifacts":{"tarball":"http://172.17.0.1:8002/linux-mainline-master-v6.1-rc8-3-gbce9332220bd.tar.gz"},"created":"2022-12-06T04:59:08.959000","updated":"2022-12-06T05:11:33.098000","timeout":"2022-12-07T04:59:08.959000","holdoff":"2022-12-06T05:11:30.873000"}],"total":1,"limit":50,"offset":0}
359+
$ curl 'http://localhost:8001/latest/nodes?kind=checkout&created__gt=2022-12-06T04:59:08.102000'
143360
```
144361

145362
> **Note** In order to support comparison operators in URL request parameters, models can not contain `__` in the field name.
146363
364+
Additionally, the `re` operator offers some basic regular expression
365+
matching capabilities for query parameters. For instance:
366+
367+
```
368+
$ curl 'http://localhost:8001/latest/nodes?kind=kbuild&name__re=x86'
369+
```
370+
371+
returns all Kbuild nodes with the string "x86" in the node name.
372+
147373
Nodes with `null` fields can also be retrieved using the endpoint.
148374
For example, the below command will get all the nodes with `parent` field set to `null`:
149375

150376
```
151377
$ curl 'http://localhost:8001/latest/nodes?parent=null'
152-
"items":[{"_id":"63c549319fb3b62c7626e7f9","kind":"node","name":"checkout","path":["checkout"],"group":null,"revision":{"tree":"kernelci","url":"https://github.com/kernelci/linux.git","branch":"staging-mainline","commit":"1385303d0d85c68473d8901d69c7153b03a3150b","describe":"staging-mainline-20230115.1","version":{"version":6,"patchlevel":2,"sublevel":null,"extra":"-rc4-2-g1385303d0d85","name":null}},"parent":null,"state":"available","result":null,"artifacts":{"tarball":"http://172.17.0.1:8002/linux-kernelci-staging-mainline-staging-mainline-20230115.1.tar.gz"},"created":"2023-01-16T12:55:13.879000","updated":"2023-01-16T12:55:51.780000","timeout":"2023-01-16T13:55:13.877000","holdoff":"2023-01-16T13:05:51.776000"},{"_id":"63c549329fb3b62c7626e7fa","kind":"node","name":"checkout","path":["checkout"],"group":null,"revision":{"tree":"kernelci","url":"https://github.com/kernelci/linux.git","branch":"staging-next","commit":"39384a5d7e2eb2f28039a92c022aed886a675fbf","describe":"staging-next-20230116.0","version":{"version":6,"patchlevel":2,"sublevel":null,"extra":"-rc4-5011-g39384a5d7e2e","name":null}},"parent":null,"state":"available","result":null,"artifacts":{"tarball":"http://172.17.0.1:8002/linux-kernelci-staging-next-staging-next-20230116.0.tar.gz"},"created":"2023-01-16T12:55:14.706000","updated":"2023-01-16T12:56:30.886000","timeout":"2023-01-16T13:55:14.703000","holdoff":"2023-01-16T13:06:30.882000"}],"total":2,"limit":50,"offset":0}
378+
"items":[{"_id":"63c549319fb3b62c7626e7f9","kind":"node","name":"checkout","path":["checkout"],"group":null,"data":{"kernel_revision":{"tree":"kernelci","url":"https://github.com/kernelci/linux.git","branch":"staging-mainline","commit":"1385303d0d85c68473d8901d69c7153b03a3150b","describe":"staging-mainline-20230115.1","version":{"version":6,"patchlevel":2,"sublevel":null,"extra":"-rc4-2-g1385303d0d85","name":null}}},"parent":null,"state":"available","result":null,"artifacts":{"tarball":"http://172.17.0.1:8002/linux-kernelci-staging-mainline-staging-mainline-20230115.1.tar.gz"},"created":"2023-01-16T12:55:13.879000","updated":"2023-01-16T12:55:51.780000","timeout":"2023-01-16T13:55:13.877000","holdoff":"2023-01-16T13:05:51.776000"},{"_id":"63c549329fb3b62c7626e7fa","kind":"node","name":"checkout","path":["checkout"],"group":null,"data":{"kernel_revision":{"tree":"kernelci","url":"https://github.com/kernelci/linux.git","branch":"staging-next","commit":"39384a5d7e2eb2f28039a92c022aed886a675fbf","describe":"staging-next-20230116.0","version":{"version":6,"patchlevel":2,"sublevel":null,"extra":"-rc4-5011-g39384a5d7e2e","name":null}}},"parent":null,"state":"available","result":null,"artifacts":{"tarball":"http://172.17.0.1:8002/linux-kernelci-staging-next-staging-next-20230116.0.tar.gz"},"created":"2023-01-16T12:55:14.706000","updated":"2023-01-16T12:56:30.886000","timeout":"2023-01-16T13:55:14.703000","holdoff":"2023-01-16T13:06:30.882000"}],"total":2,"limit":50,"offset":0}
153379
```
154380

155381
Please make sure that the query parameter provided with the `null` value in the request exists in the `Node` schema. Otherwise, the API will behave unexpectedly and return all the nodes.
@@ -167,14 +393,18 @@ $ curl -X 'PUT' \
167393
-H 'Content-Type: application/json' \
168394
-d '{
169395
"name":"checkout-test",
170-
"revision":{"tree":"mainline",
171-
"url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
172-
"branch":"master",
173-
"commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26",
174-
"describe":"v5.16-rc4-31-g2a987e65025e"},
396+
"data":{
397+
"kernel_revision":{
398+
"tree":"mainline",
399+
"url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
400+
"branch":"master",
401+
"commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26",
402+
"describe":"v5.16-rc4-31-g2a987e65025e"
403+
},
404+
},
175405
"created":"2022-02-02T11:23:03.157648"
176406
}'
177-
{"_id":"61bda8f2eb1a63d2b7152418","kind":"node","name":"checkout-test","revision":{"tree":"mainline","url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git","branch":"master","commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26","describe":"v5.16-rc4-31-g2a987e65025e"},"parent":null,"status":"pending","result":null, "created":"2022-02-02T11:23:03.157648", "updated":"2022-02-02T12:23:03.157648"}
407+
{"id":"61bda8f2eb1a63d2b7152418","kind":"node","name":"checkout-test","data":{"kernel_revision":{"tree":"mainline","url":"https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git","branch":"master","commit":"2a987e65025e2b79c6d453b78cb5985ac6e5eb26","describe":"v5.16-rc4-31-g2a987e65025e"}},"parent":null,"status":"pending","result":null, "created":"2022-02-02T11:23:03.157648", "updated":"2022-02-02T12:23:03.157648"}
178408
```
179409

180410
### Getting Nodes count
@@ -190,7 +420,7 @@ To get count of nodes matching provided attributes, use `/count` endpoint with q
190420
```
191421
$ curl http://localhost:8001/latest/count?name=checkout
192422
3
193-
$ curl http://localhost:8001/latest/count?revision.branch=staging-mainline
423+
$ curl http://localhost:8001/latest/count?data.kernel_revision.branch=staging-mainline
194424
1
195425
```
196426

0 commit comments

Comments
 (0)