Skip to content
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

[DOCS] Add space_id path parameter to saved_object APIs #47627

Merged
merged 4 commits into from
Oct 18, 2019
Merged

[DOCS] Add space_id path parameter to saved_object APIs #47627

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
afa7037
[DOCS] Add space_id path parameter to saved_object APIs
Oct 8, 2019
1572355
[DOCS] Apply suggested edits for #47627
Oct 16, 2019
e2c75e9
[DOCS] Apply suggested edits for #47627 to delete API
Oct 16, 2019
6d3c9b5
Merge branch 'master' into PR38788
Oct 18, 2019
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
19 changes: 14 additions & 5 deletions docs/api/saved-objects/bulk_create.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,15 @@ experimental[] Create multiple {kib} saved objects.

`POST /api/saved_objects/_bulk_create`

`POST /s/<space_id>/api/saved_objects/_bulk_create`


[[saved-objects-api-bulk-create-path-params]]
==== Path parameters

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL the default space is used.

[[saved-objects-api-bulk-create-query-params]]
==== Query parameters

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

`saved_objects`::
`saved_objects`::
(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.

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

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

`200`::
`200`::
Indicates a successful call.

[[saved-objects-api-bulk-create-example]]
==== Example

Create an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:
Create an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:

[source,js]
--------------------------------------------------
Expand All @@ -67,7 +76,7 @@ POST api/saved_objects/_bulk_create
},
{
"type": "dashboard",
"id": "my-dashboard",
"id": "be3733a0-9efe-11e7-acb3-3dab96693fab",
"attributes": {
"title": "Look at my dashboard"
}
Expand All @@ -91,7 +100,7 @@ The API returns the following:
}
},
{
"id": "my-dashboard",
"id": "be3733a0-9efe-11e7-acb3-3dab96693fab",
"type": "dashboard",
"error": {
"statusCode": 409,
Expand Down
20 changes: 14 additions & 6 deletions docs/api/saved-objects/bulk_get.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,36 +11,44 @@ experimental[] Retrieves multiple {kib} saved objects by ID.

`POST /api/saved_objects/_bulk_get`

`POST /s/<space_id>/api/saved_objects/_bulk_get`

[[saved-objects-api-bulk-get-path-params]]
==== Path parameters

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL the default space is used.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a comma in between URL and the


[[saved-objects-api-bulk-get-request-body]]
==== Request Body

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

`id`::
(Required, string) ID of the retrieved object.
(Required, string) ID of the retrieved object. This can be a Kibana's unique identifier or a custom one.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would change the second sentence to:

The ID includes the {kib} unique identifier or a custom identifier.


`fields`::
(Optional, array) The fields returned in the object response.

[[saved-objects-api-bulk-get-response-body]]
==== Response body

`saved_objects`::
`saved_objects`::
(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.

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

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

`200`::
`200`::
Indicates a successfully call.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

successfully should be successful


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

Retrieve an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:
Retrieve an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:

[source,js]
--------------------------------------------------
Expand All @@ -52,7 +60,7 @@ POST api/saved_objects/_bulk_get
},
{
"type": "dashboard",
"id": "my-dashboard"
"id": "be3733a0-9efe-11e7-acb3-3dab96693fab"
}
]
--------------------------------------------------
Expand Down
9 changes: 7 additions & 2 deletions docs/api/saved-objects/create.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,14 @@ experimental[] Create a {kib} saved object.

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

`POST /s/<space_id>/saved_objects/<type>`

[[saved-objects-api-create-path-params]]
==== Path parameters

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL the default space is used.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a comma in between URL and the


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

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

`200`::
`200`::
Indicates a successful call.

[[saved-objects-api-create-example]]
==== Example

Expand Down
9 changes: 7 additions & 2 deletions docs/api/saved-objects/delete.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<titleabbrev>Delete object</titleabbrev>
++++

experimental[] Remove a {kib} saved object.
experimental[] Remove a {kib} saved object.

WARNING: Once you delete a saved object, _it cannot be recovered_.

Expand All @@ -13,9 +13,14 @@ WARNING: Once you delete a saved object, _it cannot be recovered_.

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

`DELETE /s/<space_id>/api/saved_objects/<type>/<id>`

[[saved-objects-api-delete-path-params]]
==== Path parameters

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL the default space is used.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a comma in between URL and the


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

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

`200`::
`200`::
Indicates a successful call.

==== Examples
Expand Down
14 changes: 11 additions & 3 deletions docs/api/saved-objects/export.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,23 @@ experimental[] Retrieve a set of saved objects that you want to import into {kib

`POST /api/saved_objects/_export`

`POST /s/<space_id>/api/saved_objects/_export`

[[saved-objects-api-export-path-params]]
==== Path parameters

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL the default space is used.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a comma in between URL and the


[[saved-objects-api-export-request-request-body]]
==== Request body

`type`::
(Optional, array|string) The saved object types to include in the export.

`objects`::
(Optional, array) A list of objects to export.

`includeReferencesDeep`::
(Optional, boolean) Includes all of the referenced objects in the exported objects.

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

`200`::
`200`::
Indicates a successful call.

[[ssaved-objects-api-create-example]]
Expand Down
27 changes: 17 additions & 10 deletions docs/api/saved-objects/find.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,33 +11,41 @@ experimental[] Retrieve a paginated set of {kib} saved objects by various condit

`GET /api/saved_objects/_find`

`GET /s/<space_id>/api/saved_objects/_find`

[[saved-objects-api-find-path-params]]
==== Path parameters

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL the default space is used.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a comma in between URL and the


[[saved-objects-api-find-query-params]]
==== Query Parameters

`type`::
(Required, array|string) The saved object types to include in the export.

`per_page`::
(Optional, number) The number of objects to return per page.

`page`::
(Optional, number) The page of objects to return.

`search`::
(Optional, string) An Elasticsearch {ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that filters the objects in the response.

`default_search_operator`::
(Optional, string) The default operator to use for the `simple_query_string`.

`search_fields`::
(Optional, array|string) The fields to perform the `simple_query_string` parsed query against.

`fields`::
(Optional, array|string) The fields to return in the response.

`sort_field`::
(Optional, string) The field that sorts the response.

`has_reference`::
(Optional, object) Filters to objects that have a relationship with the type and ID combination.

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

`200`::
`200`::
Indicates a successful call.

==== Examples
Expand Down Expand Up @@ -87,4 +95,3 @@ query parameter for each value:
GET api/saved_objects/_find?fields=id&fields=title
--------------------------------------------------
// KIBANA

67 changes: 65 additions & 2 deletions docs/api/saved-objects/get.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,15 @@ experimental[] Retrieve a single {kib} saved object by ID.

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

`GET /s/<space_id>/api/saved_objects/<type>/<id>`

[[saved-objects-api-get-params]]
==== Path parameters

`space_id`::
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL the default space is used.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a comma in between URL and the



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

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

`200`::
`200`::
Indicates a successful call.

[[saved-objects-api-get-example]]
[[saved-objects-api-get-example]]
==== Example

Retrieve the index pattern object with the `my-pattern` ID:
Expand All @@ -50,3 +56,60 @@ The API returns the following:
}
}
--------------------------------------------------

The following example retrieves a dashboard object in the `testspace` by id.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

id should be ID


[source,js]
--------------------------------------------------
GET /s/testspace/api/saved_objects/dashboard/7adfa750-4c81-11e8-b3d7-01146121b73d
--------------------------------------------------
// KIBANA

A successful call returns a response code of `200` and a response body
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove A successful call returns a response code of 200 and a response body containing a JSON structure similar to the following example:, then replace with:

The API returns the following:

containing a JSON structure similar to the following example:

[source,js]
--------------------------------------------------
{
"id": "7adfa750-4c81-11e8-b3d7-01146121b73d",
"type": "dashboard",
"updated_at": "2019-07-23T00:11:07.059Z",
"version": "WzQ0LDFd",
"attributes": {
"title": "[Flights] Global Flight Dashboard",
"hits": 0,
"description": "Analyze mock flight data for ES-Air, Logstash Airways, Kibana Airlines and JetBeats",
"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\"}]",
"optionsJSON": "{\"hidePanelTitles\":false,\"useMargins\":true}",
"version": 1,
"timeRestore": true,
"timeTo": "now",
"timeFrom": "now-24h",
"refreshInterval": {
"display": "15 minutes",
"pause": false,
"section": 2,
"value": 900000
},
"kibanaSavedObjectMeta": {
"searchSourceJSON": "{\"query\":{\"language\":\"kuery\",\"query\":\"\"},\"filter\":[],\"highlightAll\":true,\"version\":true}"
}
},
"references": [
{
"name": "panel_0",
"type": "visualization",
"id": "aeb212e0-4c84-11e8-b3d7-01146121b73d"
},
. . .
{
"name": "panel_18",
"type": "visualization",
"id": "ed78a660-53a0-11e8-acbd-0be0ad9d822b"
}
],
"migrationVersion": {
"dashboard": "7.0.0"
}
}
--------------------------------------------------
Loading