Skip to content

Commit 4aca4d5

Browse files
author
Melori Arellano
authored
[DOCS] Add space_id path parameter to saved_object APIs (#47627) (#60971)
* [DOCS] Add space_id path parameter to saved_object APIs * [DOCS] Apply suggested edits for #47627 * [DOCS] Apply suggested edits for #47627 to delete API
1 parent 4c30218 commit 4aca4d5

File tree

10 files changed

+172
-47
lines changed

10 files changed

+172
-47
lines changed

‎docs/api/saved-objects/bulk_create.asciidoc‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,15 @@ experimental[] Create multiple {kib} saved objects.
1111

1212
`POST /api/saved_objects/_bulk_create`
1313

14+
`POST /s/<space_id>/api/saved_objects/_bulk_create`
15+
16+
17+
[[saved-objects-api-bulk-create-path-params]]
18+
==== Path parameters
19+
20+
`space_id`::
21+
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL the default space is used.
22+
1423
[[saved-objects-api-bulk-create-query-params]]
1524
==== Query parameters
1625

@@ -38,21 +47,21 @@ experimental[] Create multiple {kib} saved objects.
3847
[[saved-objects-api-bulk-create-response-body]]
3948
==== Response body
4049

41-
`saved_objects`::
50+
`saved_objects`::
4251
(array) Top-level property the contains objects that represent the response for each of the requested objects. The order of the objects in the response is identical to the order of the objects in the request.
4352

4453
Saved objects that are unable to persist are replaced with an error object.
4554

4655
[[saved-objects-api-bulk-create-codes]]
4756
==== Response code
4857

49-
`200`::
58+
`200`::
5059
Indicates a successful call.
5160

5261
[[saved-objects-api-bulk-create-example]]
5362
==== Example
5463

55-
Create an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:
64+
Create an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:
5665

5766
[source,js]
5867
--------------------------------------------------
@@ -67,7 +76,7 @@ POST api/saved_objects/_bulk_create
6776
},
6877
{
6978
"type": "dashboard",
70-
"id": "my-dashboard",
79+
"id": "be3733a0-9efe-11e7-acb3-3dab96693fab",
7180
"attributes": {
7281
"title": "Look at my dashboard"
7382
}
@@ -91,7 +100,7 @@ The API returns the following:
91100
}
92101
},
93102
{
94-
"id": "my-dashboard",
103+
"id": "be3733a0-9efe-11e7-acb3-3dab96693fab",
95104
"type": "dashboard",
96105
"error": {
97106
"statusCode": 409,

‎docs/api/saved-objects/bulk_get.asciidoc‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,36 +11,44 @@ experimental[] Retrieves multiple {kib} saved objects by ID.
1111

1212
`POST /api/saved_objects/_bulk_get`
1313

14+
`POST /s/<space_id>/api/saved_objects/_bulk_get`
15+
16+
[[saved-objects-api-bulk-get-path-params]]
17+
==== Path parameters
18+
19+
`space_id`::
20+
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
21+
1422
[[saved-objects-api-bulk-get-request-body]]
1523
==== Request Body
1624

1725
`type`::
1826
(Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`.
1927

2028
`id`::
21-
(Required, string) ID of the retrieved object.
29+
(Required, string) ID of the retrieved object. The ID includes the {kib} unique identifier or a custom identifier.
2230

2331
`fields`::
2432
(Optional, array) The fields returned in the object response.
25-
33+
2634
[[saved-objects-api-bulk-get-response-body]]
2735
==== Response body
2836

29-
`saved_objects`::
37+
`saved_objects`::
3038
(array) Top-level property the contains objects that represent the response for each of the requested objects. The order of the objects in the response is identical to the order of the objects in the request.
3139

3240
Saved objects that are unable to persist are replaced with an error object.
3341

3442
[[saved-objects-api-bulk-get-body-codes]]
3543
==== Response code
3644

37-
`200`::
38-
Indicates a successfully call.
45+
`200`::
46+
Indicates a successful call.
3947

4048
[[saved-objects-api-bulk-get-body-example]]
4149
==== Example
4250

43-
Retrieve an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:
51+
Retrieve an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:
4452

4553
[source,js]
4654
--------------------------------------------------
@@ -52,7 +60,7 @@ POST api/saved_objects/_bulk_get
5260
},
5361
{
5462
"type": "dashboard",
55-
"id": "my-dashboard"
63+
"id": "be3733a0-9efe-11e7-acb3-3dab96693fab"
5664
}
5765
]
5866
--------------------------------------------------

‎docs/api/saved-objects/create.asciidoc‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,14 @@ experimental[] Create a {kib} saved object.
1313

1414
`POST /api/saved_objects/<type>/<id>`
1515

16+
`POST /s/<space_id>/saved_objects/<type>`
17+
1618
[[saved-objects-api-create-path-params]]
1719
==== Path parameters
1820

21+
`space_id`::
22+
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
23+
1924
`<type>`::
2025
(Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`.
2126

@@ -44,9 +49,9 @@ any data that you send to the API is properly formed.
4449
[[saved-objects-api-create-request-codes]]
4550
==== Response code
4651

47-
`200`::
52+
`200`::
4853
Indicates a successful call.
49-
54+
5055
[[saved-objects-api-create-example]]
5156
==== Example
5257

‎docs/api/saved-objects/delete.asciidoc‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,14 @@ WARNING: Once you delete a saved object, _it cannot be recovered_.
1313

1414
`DELETE /api/saved_objects/<type>/<id>`
1515

16+
`DELETE /s/<space_id>/api/saved_objects/<type>/<id>`
17+
1618
[[saved-objects-api-delete-path-params]]
1719
==== Path parameters
1820

21+
`space_id`::
22+
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
23+
1924
`type`::
2025
(Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`.
2126

@@ -25,7 +30,7 @@ WARNING: Once you delete a saved object, _it cannot be recovered_.
2530
[[saved-objects-api-delete-response-codes]]
2631
==== Response code
2732

28-
`200`::
33+
`200`::
2934
Indicates a successful call.
3035

3136
==== Examples

‎docs/api/saved-objects/export.asciidoc‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,23 @@ experimental[] Retrieve a set of saved objects that you want to import into {kib
1111

1212
`POST /api/saved_objects/_export`
1313

14+
`POST /s/<space_id>/api/saved_objects/_export`
15+
16+
[[saved-objects-api-export-path-params]]
17+
==== Path parameters
18+
19+
`space_id`::
20+
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
21+
1422
[[saved-objects-api-export-request-request-body]]
1523
==== Request body
1624

1725
`type`::
1826
(Optional, array|string) The saved object types to include in the export.
19-
27+
2028
`objects`::
2129
(Optional, array) A list of objects to export.
22-
30+
2331
`includeReferencesDeep`::
2432
(Optional, boolean) Includes all of the referenced objects in the exported objects.
2533

@@ -33,7 +41,7 @@ The format of the response body includes newline delimited JSON.
3341
[[export-objects-api-create-request-codes]]
3442
==== Response code
3543

36-
`200`::
44+
`200`::
3745
Indicates a successful call.
3846

3947
[[ssaved-objects-api-create-example]]

‎docs/api/saved-objects/find.asciidoc‎

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,33 +11,41 @@ experimental[] Retrieve a paginated set of {kib} saved objects by various condit
1111

1212
`GET /api/saved_objects/_find`
1313

14+
`GET /s/<space_id>/api/saved_objects/_find`
15+
16+
[[saved-objects-api-find-path-params]]
17+
==== Path parameters
18+
19+
`space_id`::
20+
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
21+
1422
[[saved-objects-api-find-query-params]]
1523
==== Query Parameters
1624

1725
`type`::
1826
(Required, array|string) The saved object types to include in the export.
19-
27+
2028
`per_page`::
2129
(Optional, number) The number of objects to return per page.
22-
30+
2331
`page`::
2432
(Optional, number) The page of objects to return.
25-
33+
2634
`search`::
2735
(Optional, string) An Elasticsearch {ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that filters the objects in the response.
28-
36+
2937
`default_search_operator`::
3038
(Optional, string) The default operator to use for the `simple_query_string`.
31-
39+
3240
`search_fields`::
3341
(Optional, array|string) The fields to perform the `simple_query_string` parsed query against.
34-
42+
3543
`fields`::
3644
(Optional, array|string) The fields to return in the response.
37-
45+
3846
`sort_field`::
3947
(Optional, string) The field that sorts the response.
40-
48+
4149
`has_reference`::
4250
(Optional, object) Filters to objects that have a relationship with the type and ID combination.
4351

@@ -47,7 +55,7 @@ change. Use the find API for traditional paginated results, but avoid using it t
4755
[[saved-objects-api-find-request-codes]]
4856
==== Response code
4957

50-
`200`::
58+
`200`::
5159
Indicates a successful call.
5260

5361
==== Examples
@@ -87,4 +95,3 @@ query parameter for each value:
8795
GET api/saved_objects/_find?fields=id&fields=title
8896
--------------------------------------------------
8997
// KIBANA
90-

‎docs/api/saved-objects/get.asciidoc‎

Lines changed: 64 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,15 @@ experimental[] Retrieve a single {kib} saved object by ID.
1111

1212
`GET /api/saved_objects/<type>/<id>`
1313

14+
`GET /s/<space_id>/api/saved_objects/<type>/<id>`
15+
1416
[[saved-objects-api-get-params]]
1517
==== Path parameters
1618

19+
`space_id`::
20+
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
21+
22+
1723
`type`::
1824
(Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`, and `timelion-sheet`.
1925

@@ -23,10 +29,10 @@ experimental[] Retrieve a single {kib} saved object by ID.
2329
[[saved-objects-api-get-codes]]
2430
==== Response code
2531

26-
`200`::
32+
`200`::
2733
Indicates a successful call.
2834

29-
[[saved-objects-api-get-example]]
35+
[[saved-objects-api-get-example]]
3036
==== Example
3137

3238
Retrieve the index pattern object with the `my-pattern` ID:
@@ -50,3 +56,59 @@ The API returns the following:
5056
}
5157
}
5258
--------------------------------------------------
59+
60+
The following example retrieves a dashboard object in the `testspace` by id.
61+
62+
[source,js]
63+
--------------------------------------------------
64+
GET /s/testspace/api/saved_objects/dashboard/7adfa750-4c81-11e8-b3d7-01146121b73d
65+
--------------------------------------------------
66+
// KIBANA
67+
68+
The API returns the following:
69+
70+
[source,js]
71+
--------------------------------------------------
72+
{
73+
"id": "7adfa750-4c81-11e8-b3d7-01146121b73d",
74+
"type": "dashboard",
75+
"updated_at": "2019-07-23T00:11:07.059Z",
76+
"version": "WzQ0LDFd",
77+
"attributes": {
78+
"title": "[Flights] Global Flight Dashboard",
79+
"hits": 0,
80+
"description": "Analyze mock flight data for ES-Air, Logstash Airways, Kibana Airlines and JetBeats",
81+
"panelsJSON": "[{\"panelIndex\":\"1\",\"gridData\":{\"x\":0,\"y\":0,\"w\":32,\"h\":7,\"i\":\"1\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_0\"},{\"panelIndex\":\"3\",\"gridData\":{\"x\":17,\"y\":7,\"w\":23,\"h\":12,\"i\":\"3\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Average Ticket Price\":\"#0A50A1\",\"Flight Count\":\"#82B5D8\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_1\"},{\"panelIndex\":\"4\",\"gridData\":{\"x\":0,\"y\":85,\"w\":48,\"h\":15,\"i\":\"4\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_2\"},{\"panelIndex\":\"5\",\"gridData\":{\"x\":0,\"y\":7,\"w\":17,\"h\":12,\"i\":\"5\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"ES-Air\":\"#447EBC\",\"JetBeats\":\"#65C5DB\",\"Kibana Airlines\":\"#BA43A9\",\"Logstash Airways\":\"#E5AC0E\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_3\"},{\"panelIndex\":\"6\",\"gridData\":{\"x\":24,\"y\":33,\"w\":24,\"h\":14,\"i\":\"6\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Carrier Delay\":\"#5195CE\",\"Late Aircraft Delay\":\"#1F78C1\",\"NAS Delay\":\"#70DBED\",\"No Delay\":\"#BADFF4\",\"Security Delay\":\"#052B51\",\"Weather Delay\":\"#6ED0E0\"}}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_4\"},{\"panelIndex\":\"7\",\"gridData\":{\"x\":24,\"y\":19,\"w\":24,\"h\":14,\"i\":\"7\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_5\"},{\"panelIndex\":\"10\",\"gridData\":{\"x\":0,\"y\":35,\"w\":24,\"h\":12,\"i\":\"10\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Count\":\"#1F78C1\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_6\"},{\"panelIndex\":\"13\",\"gridData\":{\"x\":10,\"y\":19,\"w\":14,\"h\":8,\"i\":\"13\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Count\":\"#1F78C1\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_7\"},{\"panelIndex\":\"14\",\"gridData\":{\"x\":10,\"y\":27,\"w\":14,\"h\":8,\"i\":\"14\"},\"embeddableConfig\":{\"vis\":{\"colors\":{\"Count\":\"#1F78C1\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_8\"},{\"panelIndex\":\"18\",\"gridData\":{\"x\":24,\"y\":70,\"w\":24,\"h\":15,\"i\":\"18\"},\"embeddableConfig\":{\"mapCenter\":[27.421687059550266,15.371002131141724],\"mapZoom\":1},\"version\":\"6.3.0\",\"panelRefName\":\"panel_9\"},{\"panelIndex\":\"21\",\"gridData\":{\"x\":0,\"y\":62,\"w\":48,\"h\":8,\"i\":\"21\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_10\"},{\"panelIndex\":\"22\",\"gridData\":{\"x\":32,\"y\":0,\"w\":16,\"h\":7,\"i\":\"22\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_11\"},{\"panelIndex\":\"23\",\"gridData\":{\"x\":0,\"y\":70,\"w\":24,\"h\":15,\"i\":\"23\"},\"embeddableConfig\":{\"mapCenter\":[42.19556096274418,9.536742995308601e-7],\"mapZoom\":1},\"version\":\"6.3.0\",\"panelRefName\":\"panel_12\"},{\"panelIndex\":\"25\",\"gridData\":{\"x\":0,\"y\":19,\"w\":10,\"h\":8,\"i\":\"25\"},\"embeddableConfig\":{\"vis\":{\"defaultColors\":{\"0 - 50\":\"rgb(247,251,255)\",\"100 - 150\":\"rgb(107,174,214)\",\"150 - 200\":\"rgb(33,113,181)\",\"200 - 250\":\"rgb(8,48,107)\",\"50 - 100\":\"rgb(198,219,239)\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_13\"},{\"panelIndex\":\"27\",\"gridData\":{\"x\":0,\"y\":27,\"w\":10,\"h\":8,\"i\":\"27\"},\"embeddableConfig\":{\"vis\":{\"defaultColors\":{\"0 - 50\":\"rgb(247,251,255)\",\"100 - 150\":\"rgb(107,174,214)\",\"150 - 200\":\"rgb(33,113,181)\",\"200 - 250\":\"rgb(8,48,107)\",\"50 - 100\":\"rgb(198,219,239)\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_14\"},{\"panelIndex\":\"28\",\"gridData\":{\"x\":0,\"y\":47,\"w\":24,\"h\":15,\"i\":\"28\"},\"embeddableConfig\":{\"vis\":{\"defaultColors\":{\"0 -* Connection #0 to host 69c72adb58fa46c69a01afdf4a6cbfd3.us-west1.gcp.cloud.es.io left intact\n 11\":\"rgb(247,251,255)\",\"11 - 22\":\"rgb(208,225,242)\",\"22 - 33\":\"rgb(148,196,223)\",\"33 - 44\":\"rgb(74,152,201)\",\"44 - 55\":\"rgb(23,100,171)\"},\"legendOpen\":false}},\"version\":\"6.3.0\",\"panelRefName\":\"panel_15\"},{\"panelIndex\":\"29\",\"gridData\":{\"x\":40,\"y\":7,\"w\":8,\"h\":6,\"i\":\"29\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_16\"},{\"panelIndex\":\"30\",\"gridData\":{\"x\":40,\"y\":13,\"w\":8,\"h\":6,\"i\":\"30\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_17\"},{\"panelIndex\":\"31\",\"gridData\":{\"x\":24,\"y\":47,\"w\":24,\"h\":15,\"i\":\"31\"},\"embeddableConfig\":{},\"version\":\"6.3.0\",\"panelRefName\":\"panel_18\"}]",
82+
"optionsJSON": "{\"hidePanelTitles\":false,\"useMargins\":true}",
83+
"version": 1,
84+
"timeRestore": true,
85+
"timeTo": "now",
86+
"timeFrom": "now-24h",
87+
"refreshInterval": {
88+
"display": "15 minutes",
89+
"pause": false,
90+
"section": 2,
91+
"value": 900000
92+
},
93+
"kibanaSavedObjectMeta": {
94+
"searchSourceJSON": "{\"query\":{\"language\":\"kuery\",\"query\":\"\"},\"filter\":[],\"highlightAll\":true,\"version\":true}"
95+
}
96+
},
97+
"references": [
98+
{
99+
"name": "panel_0",
100+
"type": "visualization",
101+
"id": "aeb212e0-4c84-11e8-b3d7-01146121b73d"
102+
},
103+
. . .
104+
{
105+
"name": "panel_18",
106+
"type": "visualization",
107+
"id": "ed78a660-53a0-11e8-acbd-0be0ad9d822b"
108+
}
109+
],
110+
"migrationVersion": {
111+
"dashboard": "7.0.0"
112+
}
113+
}
114+
--------------------------------------------------

0 commit comments

Comments
 (0)