maxmustermann/kibana
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

[7.x] [DOCS] Updates API requests and examples (#60695) (#60826)

Browse source 
* [DOCS] Updates API requests and examples (#60695)

* [DOCS] Updates API requests and examples

* Review comments

* Fixed error
This commit is contained in:
Kaarina Tungseth 2020-03-26 15:11:17 -05:00 committed by GitHub
parent 972dd430b7
commit 967186bd36
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
37 changed files with 314 additions and 617 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/api/dashboard/export-dashboard.asciidoc
View file

@ -9,7 +9,7 @@ experimental[] Export dashboards and corresponding saved objects.
[[dashboard-api-export-request]]
==== Request
`GET /api/kibana/dashboards/export`
`GET <kibana host>:<port>/api/kibana/dashboards/export`
[[dashboard-api-export-params]]
==== Query parameters
@ -20,9 +20,9 @@ experimental[] Export dashboards and corresponding saved objects.
[[dashboard-api-export-response-body]]
==== Response body
`objects`::
`objects`::
(array) A top level property that includes the saved objects. The order of the objects is not guaranteed. Use the exact response body as the request body for the corresponding <<dashboard-import-api, Import dashboard API>>.
[[dashboard-api-export-codes]]
==== Response code
@ -33,10 +33,10 @@ experimental[] Export dashboards and corresponding saved objects.
[[dashboard-api-export-example]]
==== Example
[source,js]
[source,sh]
--------------------------------------------------
GET api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c <1>
$ curl -X GET "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c" <1>
--------------------------------------------------
// KIBANA
<1> The dashboard ID is `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`.
<1> The dashboard ID is `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`.

6
docs/api/dashboard/import-dashboard.asciidoc
View file

@ -9,7 +9,7 @@ experimental[] Import dashboards and corresponding saved objects.
[[dashboard-api-import-request]]
==== Request
`POST /api/kibana/dashboards/import`
`POST <kibana host>:<port>/api/kibana/dashboards/import`
[[dashboard-api-import-params]]
==== Query parameters
@ -40,9 +40,9 @@ Use the complete response body from the <<dashboard-api-export, Export dashboard
[[dashboard-api-import-example]]
==== Example
[source,js]
[source,sh]
--------------------------------------------------
POST api/kibana/dashboards/import?exclude=index-pattern
$ curl -X POST "localhost:5601/api/kibana/dashboards/import?exclude=index-pattern"
{
"objects": [
{

4
docs/api/features.asciidoc
View file

@ -8,7 +8,7 @@ experimental[] Retrieves all {kib} features. Features are used by spaces and sec
[[features-api-get-request]]
=== Request
`GET /api/features`
`GET <kibana host>:<port>/api/features`
[float]
[[features-api-get-codes]]
@ -23,7 +23,7 @@ experimental[] Retrieves all {kib} features. Features are used by spaces and sec
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"id": "discover",

6
docs/api/logstash-configuration-management.asciidoc
View file

@ -2,9 +2,9 @@
[[logstash-configuration-management-api]]
== Logstash configuration management APIs
Programmatically integrate with the Logstash configuration management feature.
Programmatically integrate with Logstash configuration management.
WARNING: Do not directly access the `.logstash` index. The structure of the `.logstash` index is subject to change, which could cause your integration to break. Instead, use the Logstash configuration management APIs.
WARNING: Do not directly access the `.logstash` index. The structure of the `.logstash` index is subject to change, which could cause your integration to break. Instead, use the Logstash configuration management APIs.
The following Logstash configuration management APIs are available:
@ -20,5 +20,3 @@ include::logstash-configuration-management/delete-pipeline.asciidoc[]
include::logstash-configuration-management/list-pipeline.asciidoc[]
include::logstash-configuration-management/create-logstash.asciidoc[]
include::logstash-configuration-management/retrieve-pipeline.asciidoc[]

6
docs/api/logstash-configuration-management/create-logstash.asciidoc
View file

@ -9,7 +9,7 @@ experimental[] Create a centrally-managed Logstash pipeline, or update an existi
[[logstash-configuration-management-api-create-request]]
==== Request
`PUT /api/logstash/pipeline/<id>`
`PUT <kibana host>:<port>/api/logstash/pipeline/<id>`
[[logstash-configuration-management-api-create-params]]
==== Path parameters
@ -39,9 +39,9 @@ experimental[] Create a centrally-managed Logstash pipeline, or update an existi
[[logstash-configuration-management-api-create-example]]
==== Example
[source,js]
[source,sh]
--------------------------------------------------
PUT api/logstash/pipeline/hello-world
$ curl -X PUT "localhost:5601/api/logstash/pipeline/hello-world"
{
"pipeline": "input { stdin {} } output { stdout {} }",
"settings": {

7
docs/api/logstash-configuration-management/delete-pipeline.asciidoc
View file

@ -9,7 +9,7 @@ experimental[] Delete a centrally-managed Logstash pipeline.
[[logstash-configuration-management-api-delete-request]]
==== Request
`DELETE /api/logstash/pipeline/<id>`
`DELETE <kibana host>:<port>/api/logstash/pipeline/<id>`
[[logstash-configuration-management-api-delete-params]]
==== Path parameters
@ -26,9 +26,8 @@ experimental[] Delete a centrally-managed Logstash pipeline.
[[logstash-configuration-management-api-delete-example]]
==== Example
[source,js]
[source,sh]
--------------------------------------------------
DELETE api/logstash/pipeline/hello-world
$ curl -X DELETE "localhost:5601/api/logstash/pipeline/hello-world"
--------------------------------------------------
// KIBANA

6
docs/api/logstash-configuration-management/list-pipeline.asciidoc
View file

@ -9,14 +9,14 @@ experimental[] List all centrally-managed Logstash pipelines.
[[logstash-configuration-management-api-list-request]]
==== Request
`GET /api/logstash/pipelines`
`GET <kibana host>:<port>/api/logstash/pipelines`
[[logstash-configuration-management-api-list-example]]
==== Example
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"pipelines": [
@ -35,4 +35,4 @@ The API returns the following:
}
--------------------------------------------------
<1> The `username` property appears when security is enabled, and depends on when the pipeline was created or last updated.
<1> The `username` property appears when security is enabled, and depends on when the pipeline was created or last updated.

8
docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc
View file

@ -9,20 +9,20 @@ experimental[] Retrieve a centrally-managed Logstash pipeline.
[[logstash-configuration-management-api-retrieve-request]]
==== Request
`GET /api/logstash/pipeline/<id>`
`GET <kibana host>:<port>/api/logstash/pipeline/<id>`
[[logstash-configuration-management-api-retrieve-path-params]]
==== Path parameters
`id`::
(Required, string) The pipeline ID.
[[logstash-configuration-management-api-retrieve-example]]
==== Example
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"id": "hello-world",
@ -33,4 +33,4 @@ The API returns the following:
"queue.type": "persistent"
}
}
--------------------------------------------------
--------------------------------------------------

4
docs/api/role-management.asciidoc
View file

@ -2,9 +2,9 @@
[[role-management-api]]
== {kib} role management APIs
Manage the roles that grant <<kibana-privileges, Kibana privileges>>.
Manage the roles that grant <<kibana-privileges, {kib} privileges>>.
WARNING: Do not use the {ref}/security-api.html#security-role-apis[{es} role management APIs] to manage {kib} roles.
WARNING: Do not use the {ref}/security-api.html#security-role-apis[{es} role management APIs] to manage {kib} roles.
The following {kib} role management APIs are available:

13
docs/api/role-management/delete.asciidoc
View file

@ -4,26 +4,23 @@
<titleabbrev>Delete role</titleabbrev>
++++
Delete a {kib} role.
experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."]
experimental[] Delete a {kib} role.
[[role-management-api-delete-prereqs]]
==== Prerequisite
==== Prerequisite
To use the delete role API, you must have the `manage_security` cluster privilege.
[[role-management-api-delete-request-body]]
==== Request
`DELETE /api/security/role/my_admin_role`
`DELETE <kibana host>:<port>/api/security/role/my_admin_role`
[[role-management-api-delete-response-codes]]
==== Response codes
`204`::
Indicates a successful call.
`404`::
Indicates an unsuccessful call.
Indicates an unsuccessful call.

16
docs/api/role-management/get-all.asciidoc
View file

@ -4,32 +4,30 @@
<titleabbrev>Get all roles</titleabbrev>
++++
Retrieve all {kib} roles.
experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."]
experimental[] Retrieve all {kib} roles.
[[role-management-api-get-prereqs]]
==== Prerequisite
==== Prerequisite
To use the get role API, you must have the `manage_security` cluster privilege.
[[role-management-api-retrieve-all-request-body]]
==== Request
`GET /api/security/role`
`GET <kibana host>:<port>/api/security/role`
[[role-management-api-retrieve-all-response-codes]]
==== Response code
`200`::
`200`::
Indicates a successful call.
[[role-management-api-retrieve-all-example]]
==== Example
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
[
{
@ -77,4 +75,4 @@ The API returns the following:
"kibana": [ ]
}
]
--------------------------------------------------
--------------------------------------------------

14
docs/api/role-management/get.asciidoc
View file

@ -4,32 +4,30 @@
<titleabbrev>Get specific role</titleabbrev>
++++
Retrieve a specific role.
experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."]
experimental[] Retrieve a specific role.
[[role-management-specific-api-get-prereqs]]
==== Prerequisite
==== Prerequisite
To use the get specific role API, you must have the `manage_security` cluster privilege.
[[role-management-specific-api-retrieve-all-request-body]]
===== Request
`GET /api/security/role/my_restricted_kibana_role`
`GET <kibana host>:<port>/api/security/role/my_restricted_kibana_role`
[[role-management-specific-api-retrieve-all-response-codes]]
==== Response code
`200`::
`200`::
Indicates a successful call.
[[role-management-specific-api-retrieve-all-example]]
===== Example
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"name": "my_restricted_kibana_role",

44
docs/api/role-management/put.asciidoc
View file

@ -4,15 +4,13 @@
<titleabbrev>Create or update role</titleabbrev>
++++
Create a new {kib} role, or update the attributes of an existing role. {kib} roles are stored in the
experimental[] Create a new {kib} role, or update the attributes of an existing role. {kib} roles are stored in the
{es} native realm.
experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."]
[[role-management-api-put-request]]
==== Request
`PUT /api/security/role/my_kibana_role`
`PUT <kibana host>:<port>/api/security/role/my_kibana_role`
[[role-management-api-put-prereqs]]
==== Prerequisite
@ -22,45 +20,45 @@ To use the create or update role API, you must have the `manage_security` cluste
[[role-management-api-response-body]]
==== Request body
`metadata`::
`metadata`::
(Optional, object) In the `metadata` object, keys that begin with `_` are reserved for system usage.
`elasticsearch`::
(Optional, object) {es} cluster and index privileges. Valid keys include
`elasticsearch`::
(Optional, object) {es} cluster and index privileges. Valid keys include
`cluster`, `indices`, and `run_as`. For more information, see
{ref}/defining-roles.html[Defining roles].
`kibana`::
`kibana`::
(list) Objects that specify the <<kibana-privileges, Kibana privileges>> for the role:
`base` :::
`base` :::
(Optional, list) A base privilege. When specified, the base must be `["all"]` or `["read"]`.
When the `base` privilege is specified, you are unable to use the `feature` section.
"all" grants read/write access to all {kib} features for the specified spaces.
"read" grants read-only access to all {kib} features for the specified spaces.
`feature` :::
`feature` :::
(object) Contains privileges for specific features.
When the `feature` privileges are specified, you are unable to use the `base` section.
To retrieve a list of available features, use the <<features-api-get, features API>>.
`spaces` :::
`spaces` :::
(list) The spaces to apply the privileges to.
To grant access to all spaces, set to `["*"]`, or omit the value.
[[role-management-api-put-response-codes]]
==== Response code
`204`::
`204`::
Indicates a successful call.
===== Examples
Grant access to various features in all spaces:
[source,js]
[source,sh]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
{
"metadata" : {
"version" : 1
@ -127,9 +125,9 @@ PUT /api/security/role/my_kibana_role
Grant dashboard-only access to only the Marketing space:
[source,js]
[source,sh]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
{
"metadata" : {
"version" : 1
@ -155,9 +153,9 @@ PUT /api/security/role/my_kibana_role
Grant full access to all features in the Default space:
[source,js]
[source,sh]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
{
"metadata" : {
"version" : 1
@ -182,9 +180,9 @@ PUT /api/security/role/my_kibana_role
Grant different access to different spaces:
[source,js]
[source,sh]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
{
"metadata" : {
"version" : 1
@ -216,11 +214,11 @@ PUT /api/security/role/my_kibana_role
--------------------------------------------------
// KIBANA
Grant access to {kib} and Elasticsearch:
Grant access to {kib} and {es}:
[source,js]
[source,sh]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
{
"metadata" : {
"version" : 1

11
docs/api/saved-objects/bulk_create.asciidoc
View file

@ -9,10 +9,9 @@ experimental[] Create multiple {kib} saved objects.
[[saved-objects-api-bulk-create-request]]
==== Request
`POST /api/saved_objects/_bulk_create`
`POST /s/<space_id>/api/saved_objects/_bulk_create`
`POST <kibana host>:<port>/api/saved_objects/_bulk_create`
`POST <kibana host>:<port>/s/<space_id>/api/saved_objects/_bulk_create`
[[saved-objects-api-bulk-create-path-params]]
==== Path parameters
@ -63,9 +62,9 @@ Saved objects that are unable to persist are replaced with an error object.
Create an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:
[source,js]
[source,sh]
--------------------------------------------------
POST api/saved_objects/_bulk_create
$ curl -X POST "localhost:5601/api/saved_objects/_bulk_create"
[
{
"type": "index-pattern",
@ -87,7 +86,7 @@ POST api/saved_objects/_bulk_create
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"saved_objects": [

11
docs/api/saved-objects/bulk_get.asciidoc
View file

@ -9,9 +9,9 @@ experimental[] Retrieve multiple {kib} saved objects by ID.
[[saved-objects-api-bulk-get-request]]
==== Request
`POST /api/saved_objects/_bulk_get`
`POST <kibana host>:<port>/api/saved_objects/_bulk_get`
`POST /s/<space_id>/api/saved_objects/_bulk_get`
`POST <kibana host>:<port>/s/<space_id>/api/saved_objects/_bulk_get`
[[saved-objects-api-bulk-get-path-params]]
==== Path parameters
@ -43,6 +43,7 @@ Saved objects that are unable to persist are replaced with an error object.
==== Response code
`200`::
Indicates a successful call.
[[saved-objects-api-bulk-get-body-example]]
@ -50,9 +51,9 @@ Saved objects that are unable to persist are replaced with an error object.
Retrieve an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID:
[source,js]
[source,sh]
--------------------------------------------------
POST api/saved_objects/_bulk_get
$ curl -X POST "localhost:5601/api/saved_objects/_bulk_get"
[
{
"type": "index-pattern",
@ -68,7 +69,7 @@ POST api/saved_objects/_bulk_get
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"saved_objects": [

12
docs/api/saved-objects/create.asciidoc
View file

@ -9,9 +9,11 @@ experimental[] Create {kib} saved objects.
[[saved-objects-api-create-request]]
==== Request
`POST /api/saved_objects/<type>` +
`POST <kibana host>:<port>/api/saved_objects/<type>` +
`POST /api/saved_objects/<type>/<id>`
`POST <kibana host>:<port>/api/saved_objects/<type>/<id>`
`POST <kibana host>:<port>/s/<space_id>/saved_objects/<type>`
`POST /s/<space_id>/saved_objects/<type>`
@ -55,9 +57,9 @@ any data that you send to the API is properly formed.
[[saved-objects-api-create-example]]
==== Example
[source,js]
[source,sh]
--------------------------------------------------
POST api/saved_objects/index-pattern/my-pattern
$ curl -X POST "localhost:5601/api/saved_objects/index-pattern/my-pattern"
{
"attributes": {
"title": "my-pattern-*"
@ -68,7 +70,7 @@ POST api/saved_objects/index-pattern/my-pattern
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"id": "my-pattern", <1>

12
docs/api/saved-objects/delete.asciidoc
View file

@ -4,14 +4,16 @@
<titleabbrev>Delete object</titleabbrev>
++++
experimental[] Remove {kib} saved objects.
experimental[] Remove {kib} saved objects.
WARNING: Once you delete a saved object, _it cannot be recovered_.
[[saved-objects-api-delete-request]]
==== Request
`DELETE /api/saved_objects/<type>/<id>`
`DELETE <kibana host>:<port>/api/saved_objects/<type>/<id>`
`DELETE <kibana host>:<port>/s/<space_id>/api/saved_objects/<type>/<id>`
`DELETE /s/<space_id>/api/saved_objects/<type>/<id>`
@ -33,12 +35,12 @@ WARNING: Once you delete a saved object, _it cannot be recovered_.
`200`::
Indicates a successful call.
==== Examples
==== Example
Delete an index pattern object with the `my-pattern` ID:
[source,js]
[source,sh]
--------------------------------------------------
DELETE api/saved_objects/index-pattern/my-pattern
$ curl -X DELETE "localhost:5601/api/saved_objects/index-pattern/my-pattern"
--------------------------------------------------
// KIBANA

22
docs/api/saved-objects/export.asciidoc
View file

@ -9,9 +9,9 @@ experimental[] Retrieve sets of saved objects that you want to import into {kib}
[[saved-objects-api-export-request]]
==== Request
`POST /api/saved_objects/_export`
`POST <kibana host>:<port>/api/saved_objects/_export`
`POST /s/<space_id>/api/saved_objects/_export`
`POST <kibana host>:<port>/s/<space_id>/api/saved_objects/_export`
[[saved-objects-api-export-path-params]]
==== Path parameters
@ -39,7 +39,7 @@ TIP: You must include `type` or `objects` in the request body.
[[saved-objects-api-export-request-response-body]]
==== Response body
The format of the response body is newline delimited JSON. Each exported object is exported as a valid JSON record and separated by the newline character '\n'.
The format of the response body is newline delimited JSON. Each exported object is exported as a valid JSON record and separated by the newline character '\n'.
When `excludeExportDetails=false` (the default) we append an export result details record at the end of the file after all the saved object records. The export result details object has the following format:
@ -66,9 +66,9 @@ When `excludeExportDetails=false` (the default) we append an export result detai
Export all index pattern saved objects:
[source,js]
[source,sh]
--------------------------------------------------
POST api/saved_objects/_export
$ curl -X POST "localhost:5601/api/saved_objects/_export"
{
"type": "index-pattern"
}
@ -77,9 +77,9 @@ POST api/saved_objects/_export
Export all index pattern saved objects and exclude the export summary from the stream:
[source,js]
[source,sh]
--------------------------------------------------
POST api/saved_objects/_export
$ curl -X POST "localhost:5601/api/saved_objects/_export"
{
"type": "index-pattern",
"excludeExportDetails": true
@ -89,9 +89,9 @@ POST api/saved_objects/_export
Export a specific saved object:
[source,js]
[source,sh]
--------------------------------------------------
POST api/saved_objects/_export
$ curl -X POST "localhost:5601/api/saved_objects/_export"
{
"objects": [
{
@ -105,9 +105,9 @@ POST api/saved_objects/_export
Export a specific saved object and it's related objects :
[source,js]
[source,sh]
--------------------------------------------------
POST api/saved_objects/_export
$ curl -X POST "localhost:5601/api/saved_objects/_export"
{
"objects": [
{

14
docs/api/saved-objects/find.asciidoc
View file

@ -9,9 +9,9 @@ experimental[] Retrieve a paginated set of {kib} saved objects by various condit
[[saved-objects-api-find-request]]
==== Request
`GET /api/saved_objects/_find`
`GET <kibana host>:<port>/api/saved_objects/_find`
`GET /s/<space_id>/api/saved_objects/_find`
`GET <kibana host>:<port>/s/<space_id>/api/saved_objects/_find`
[[saved-objects-api-find-path-params]]
==== Path parameters
@ -67,15 +67,15 @@ change. Use the find API for traditional paginated results, but avoid using it t
Find index patterns with titles that start with `my`:
[source,js]
[source,sh]
--------------------------------------------------
GET api/saved_objects/_find?type=index-pattern&search_fields=title&search=my*
$ curl -X GET "localhost:5601/api/saved_objects/_find?type=index-pattern&search_fields=title&search=my*"
--------------------------------------------------
// KIBANA
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"total": 1,
@ -95,8 +95,8 @@ The API returns the following:
For parameters that accept multiple values (e.g. `fields`), repeat the
query parameter for each value:
[source,js]
[source,sh]
--------------------------------------------------
GET api/saved_objects/_find?fields=id&fields=title
$ curl -X GET "localhost:5601/api/saved_objects/_find?fields=id&fields=title"
--------------------------------------------------
// KIBANA

18
docs/api/saved-objects/get.asciidoc
View file

@ -9,7 +9,9 @@ experimental[] Retrieve a single {kib} saved object by ID.
[[saved-objects-api-get-request]]
==== Request
`GET /api/saved_objects/<type>/<id>`
`GET <kibana host>:<port>/api/saved_objects/<type>/<id>`
`GET <kibana host>:<port>/s/<space_id>/api/saved_objects/<type>/<id>`
`GET /s/<space_id>/api/saved_objects/<type>/<id>`
@ -37,15 +39,15 @@ experimental[] Retrieve a single {kib} saved object by ID.
Retrieve the index pattern object with the `my-pattern` ID:
[source,js]
[source,sh]
--------------------------------------------------
GET api/saved_objects/index-pattern/my-pattern
$ curl -X GET "localhost:5601/api/saved_objects/index-pattern/my-pattern"
--------------------------------------------------
// KIBANA
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"id": "my-pattern",
@ -57,17 +59,17 @@ The API returns the following:
}
--------------------------------------------------
The following example retrieves a dashboard object in the `testspace` by id.
Retrieve a dashboard object in the `testspace` by ID:
[source,js]
[source,sh]
--------------------------------------------------
GET /s/testspace/api/saved_objects/dashboard/7adfa750-4c81-11e8-b3d7-01146121b73d
$ curl -X GET "localhost:5601/s/testspace/api/saved_objects/dashboard/7adfa750-4c81-11e8-b3d7-01146121b73d"
--------------------------------------------------
// KIBANA
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"id": "7adfa750-4c81-11e8-b3d7-01146121b73d",

25
docs/api/saved-objects/import.asciidoc
View file

@ -9,9 +9,9 @@ experimental[] Create sets of {kib} saved objects from a file created by the exp
[[saved-objects-api-import-request]]
==== Request
`POST /api/saved_objects/_import`
`POST <kibana host>:<port>/api/saved_objects/_import`
`POST /s/<space_id>/api/saved_objects/_import`
`POST <kibana host>:<port>/s/<space_id>/api/saved_objects/_import`
[[saved-objects-api-import-path-params]]
==== Path parameters
@ -55,14 +55,15 @@ The request body must include the multipart/form-data type.
Import an index pattern and dashboard:
[source,js]
[source,sh]
--------------------------------------------------
$ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson
--------------------------------------------------
// KIBANA
The `file.ndjson` file contains the following:
[source,js]
[source,sh]
--------------------------------------------------
{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}
@ -70,7 +71,7 @@ The `file.ndjson` file contains the following:
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"success": true,
@ -80,14 +81,15 @@ The API returns the following:
Import an index pattern and dashboard that includes a conflict on the index pattern:
[source,js]
[source,sh]
--------------------------------------------------
$ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson
--------------------------------------------------
// KIBANA
The `file.ndjson` file contains the following:
[source,js]
[source,sh]
--------------------------------------------------
{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}
@ -95,7 +97,7 @@ The `file.ndjson` file contains the following:
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"success": false,
@ -115,14 +117,15 @@ The API returns the following:
Import a visualization and dashboard with an index pattern for the visualization reference that doesn't exist:
[source,js]
[source,sh]
--------------------------------------------------
$ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson
--------------------------------------------------
// KIBANA
The `file.ndjson` file contains the following:
[source,js]
[source,sh]
--------------------------------------------------
{"type":"visualization","id":"my-vis","attributes":{"title":"my-vis"},"references":[{"name":"ref_0","type":"index-pattern","id":"my-pattern-*"}]}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"},"references":[{"name":"ref_0","type":"visualization","id":"my-vis"}]}
@ -130,7 +133,7 @@ The `file.ndjson` file contains the following:
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
"success": false,
"successCount": 0,

25
docs/api/saved-objects/resolve_import_errors.asciidoc
View file

@ -17,9 +17,9 @@ To resolve errors, you can:
[[saved-objects-api-resolve-import-errors-request]]
==== Request
`POST /api/saved_objects/_resolve_import_errors`
`POST <kibana host>:<port>/api/saved_objects/_resolve_import_errors`
`POST /s/<space_id>/api/saved_objects/_resolve_import_errors`
`POST <kibana host>:<port>/s/<space_id>/api/saved_objects/_resolve_import_errors`
[[saved-objects-api-resolve-import-errors-path-params]]
==== Path parameters
@ -61,21 +61,22 @@ The request body must include the multipart/form-data type.
Retry a dashboard import:
[source,js]
[source,sh]
--------------------------------------------------
$ curl -X POST "localhost:5601/api/saved_objects/_resolve_import_errors" -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"dashboard","id":"my-dashboard"}]'
--------------------------------------------------
// KIBANA
The `file.ndjson` file contains the following:
[source,js]
[source,sh]
--------------------------------------------------
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}
--------------------------------------------------
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"success": true,
@ -85,14 +86,15 @@ The API returns the following:
Resolve errors for a dashboard and overwrite the existing saved object:
[source,js]
[source,sh]
--------------------------------------------------
$ curl -X POST "localhost:5601/api/saved_objects/_resolve_import_errors" -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"dashboard","id":"my-dashboard","overwrite":true}]'
--------------------------------------------------
// KIBANA
The `file.ndjson` file contains the following:
[source,js]
[source,sh]
--------------------------------------------------
{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}
@ -100,7 +102,7 @@ The `file.ndjson` file contains the following:
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"success": true,
@ -110,21 +112,22 @@ The API returns the following:
Resolve errors for a visualization by replacing the index pattern with another:
[source,js]
[source,sh]
--------------------------------------------------
$ curl -X POST "localhost:5601/api/saved_objects/_resolve_import_errors" -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"visualization","id":"my-vis","replaceReferences":[{"type":"index-pattern","from":"missing","to":"existing"}]}]'
--------------------------------------------------
// KIBANA
The `file.ndjson` file contains the following:
[source,js]
[source,sh]
--------------------------------------------------
{"type":"visualization","id":"my-vis","attributes":{"title":"Look at my visualization"},"references":[{"name":"ref_0","type":"index-pattern","id":"missing"}]}
--------------------------------------------------
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"success": true,

10
docs/api/saved-objects/update.asciidoc
View file

@ -9,7 +9,9 @@ experimental[] Update the attributes for existing {kib} saved objects.
[[saved-objects-api-update-request]]
==== Request
`PUT /api/saved_objects/<type>/<id>`
`PUT <kibana host>:<port>/api/saved_objects/<type>/<id>`
`PUT <kibana host>:<port>/s/<space_id>/api/saved_objects/<type>/<id>`
`PUT /s/<space_id>/api/saved_objects/<type>/<id>`
@ -47,9 +49,9 @@ WARNING: When you update, attributes are not validated, which allows you to pass
Update an existing index pattern object,`my-pattern`, with a different title:
[source,js]
[source,sh]
--------------------------------------------------
PUT api/saved_objects/index-pattern/my-pattern
$ curl -X PUT "localhost:5601/api/saved_objects/index-pattern/my-pattern"
{
"attributes": {
"title": "some-other-pattern-*"
@ -60,7 +62,7 @@ PUT api/saved_objects/index-pattern/my-pattern
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"id": "my-pattern",

220
docs/api/spaces-management/copy_saved_objects.asciidoc
View file

@ -5,225 +5,75 @@
<titleabbrev>Copy saved objects to space</titleabbrev>
++++
experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
////
Use the appropriate heading levels for your book.
Add anchors for each section.
FYI: The section titles use attributes in case those terms change.
////
[[spaces-api-copy-saved-objects-request]]
==== {api-request-title}
////
This section show the basic endpoint, without the body or optional parameters.
Variables should use <...> syntax.
If an API supports both PUT and POST, include both here.
////
`POST /api/spaces/_copy_saved_objects`
`POST /s/<space_id>/api/spaces/_copy_saved_objects`
////
[[spaces-api-copy-saved-objects-prereqs]]
==== {api-prereq-title}
////
////
Optional list of prerequisites.
For example:
* A snapshot of an index created in 5.x can be restored to 6.x. You must...
* If the {es} {security-features} are enabled, you must have `write`, `monitor`,
and `manage_follow_index` index privileges...
////
[[spaces-api-copy-saved-objects-desc]]
==== {api-description-title}
Copy saved objects between spaces.
experimental[] Copy saved objects between spaces.
It also allows you to automatically copy related objects, so when you copy a `dashboard`, this can automatically copy over the
associated visualizations, index patterns, and saved searches, as required.
You can request to overwrite any objects that already exist in the target space if they share an ID, or you can use the
You can request to overwrite any objects that already exist in the target space if they share an ID, or you can use the
<<spaces-api-resolve-copy-saved-objects-conflicts, Resolve copy saved objects conflicts API>> to do this on a per-object basis.
////
Add a more detailed description the context.
Link to related APIs if appropriate.
[[spaces-api-copy-saved-objects-request]]
==== {api-request-title}
Guidelines for parameter documentation
***************************************
* Use a definition list.
* End each definition with a period.
* Include whether the parameter is Optional or Required and the data type.
* Include default values as the last sentence of the first paragraph.
* Include a range of valid values, if applicable.
* If the parameter requires a specific delimiter for multiple values, say so.
* If the parameter supports wildcards, ditto.
* For large or nested objects, consider linking to a separate definition list.
***************************************
////
`POST <kibana host>:<port>/api/spaces/_copy_saved_objects`
`POST <kibana host>:<port>/s/<space_id>/api/spaces/_copy_saved_objects`
[[spaces-api-copy-saved-objects-path-params]]
==== {api-path-parms-title}
////
A list of all the parameters within the path of the endpoint (before the query string (?)).
For example:
`<follower_index>`::
(Required, string) Name of the follower index
////
`space_id`::
(Optional, string) Identifies the source space from which saved objects will be copied. If `space_id` is not specified in the URL, the default space is used.
////
[[spaces-api-copy-saved-objects-params]]
==== {api-query-parms-title}
////
////
A list of the parameters in the query string of the endpoint (after the ?).
For example:
`wait_for_active_shards`::
(Optional, integer) Specifies the number of shards to wait on being active before
responding. A shard must be restored from the leader index being active.
Restoring a follower shard requires transferring all the remote Lucene segment
files to the follower index. The default is `0`, which means waiting on none of
the shards to be active.
////
(Optional, string) The ID of the space that contains the saved objects you want to copy. When `space_id` is unspecified in the URL, the default space is used.
[[spaces-api-copy-saved-objects-request-body]]
==== {api-request-body-title}
////
A list of the properties you can specify in the body of the request.
For example:
`remote_cluster`::
(Required, string) The <<modules-remote-clusters,remote cluster>> that contains
the leader index.
`spaces`::
(Required, string array) The IDs of the spaces where you want to copy the specified objects.
`leader_index`::
(Required, string) The name of the index in the leader cluster to follow.
////
`spaces` ::
(Required, string array) The ids of the spaces the specified object(s) will be copied into.
`objects` ::
`objects`::
(Required, object array) The saved objects to copy.
`type` :::
`type`:::
(Required, string) The saved object type.
`id` :::
(Required, string) The saved object id.
`id`:::
(Required, string) The saved object ID.
`includeReferences` ::
`includeReferences`::
(Optional, boolean) When set to `true`, all saved objects related to the specified saved objects will also be copied into the target spaces. The default value is `false`.
`overwrite` ::
(Optional, boolean) When set to `true`, all conflicts will be automatically overidden. If a saved object with a matching `type` and `id` exists in the target space, then that version will be replaced with the version from the source space. The default value is `false`.
`overwrite`::
(Optional, boolean) When set to `true`, all conflicts are automatically overidden. When a saved object with a matching `type` and `id` exists in the target space, that version is replaced with the version from the source space. The default value is `false`.
[[spaces-api-copy-saved-objects-response-body]]
==== {api-response-body-title}
////
Response body is only required for detailed responses.
For example:
`auto_follow_stats`::
(object) An object representing stats for the auto-follow coordinator. This
object consists of the following fields:
`auto_follow_stats.number_of_successful_follow_indices`:::
(long) the number of indices that the auto-follow coordinator successfully
followed
...
////
`<space_id>`::
(object) Specifies the dynamic keys that are included in the response. An object describing the result of the copy operation for this particular space.
(object) An object that describes the result of the copy operation for the space. Includes the dynamic keys in the response.
`success`:::
(boolean) Indicates if the copy operation was successful. Note that some objects may have been copied even if this is set to `false`. Consult the `successCount` and `errors` properties of the response for additional information.
(boolean) The copy operation was successful. When set to `false`, some objects may have been copied. For additional information, refer to the `successCount` and `errors` properties.
`successCount`:::
(number) The number of objects that were successfully copied.
(number) The number of objects that successfully copied.
`errors`:::
(Optional, array) Collection of any errors that were encountered during the copy operation. If any errors are reported, then the `success` flag will be set to `false`.
(Optional, array) The errors that occurred during the copy operation. When errors are reported, the `success` flag is set to `false`.v
`id`::::
(string) The saved object id which failed to copy.
(string) The saved object ID that failed to copy.
`type`::::
(string) The type of saved object which failed to copy.
(string) The type of saved object that failed to copy.
`error`::::
(object) The error which caused the copy operation to fail.
(object) The error that caused the copy operation to fail.
`type`:::::
(string) Indicates the type of error. May be one of: `conflict`, `unsupported_type`, `missing_references`, `unknown`. Errors marked as `conflict` may be resolved by using the <<spaces-api-resolve-copy-saved-objects-conflicts, Resolve copy saved objects conflicts API>>.
////
[[spaces-api-copy-saved-objects-response-codes]]
==== {api-response-codes-title}
////
////
Response codes are only required when needed to understand the response body.
For example:
`200`::
Indicates all listed indices or index aliases exist.
`404`::
Indicates one or more listed indices or index aliases **do not** exist.
////
(string) The type of error. For example, `unsupported_type`, `missing_references`, or `unknown`. Errors marked as `conflict` may be resolved by using the <<spaces-api-resolve-copy-saved-objects-conflicts, Resolve copy saved objects conflicts API>>.
[[spaces-api-copy-saved-objects-example]]
==== {api-examples-title}
////
Optional brief example.
Use an 'Examples' heading if you include multiple examples.
Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` and `sales` spaces:
[source,js]
[source,sh]
----
PUT /follower_index/_ccr/follow?wait_for_active_shards=1
{
"remote_cluster" : "remote_cluster",
"leader_index" : "leader_index",
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}
----
// CONSOLE
// TEST[setup:remote_cluster_and_leader_index]
The API returns the following result:
[source,js]
----
{
"follow_index_created" : true,
"follow_index_shards_acked" : true,
"index_following_started" : true
}
----
// TESTRESPONSE
////
The following example attempts to copy a dashboard with id `my-dashboard`, including all references from the `default` space to the `marketing` and `sales` spaces. The `marketing` space succeeds, while the `sales` space fails due to a conflict on the underlying index pattern:
[source,js]
----
POST /api/spaces/_copy_saved_objects
$ curl -X POST "localhost:5601/api/spaces/_copy_saved_objects"
{
"objects": [{
"type": "dashboard",
@ -235,9 +85,9 @@ POST /api/spaces/_copy_saved_objects
----
// KIBANA
The API returns the following result:
The API returns the following:
[source,js]
[source,sh]
----
{
"marketing": {
@ -258,11 +108,13 @@ The API returns the following result:
}
----
The following example successfully copies a visualization with id `my-viz` from the `marketing` space to the `default` space:
The `marketing` space succeeds, but the `sales` space fails due to a conflict in the index pattern.
[source,js]
Copy a visualization with the `my-viz` ID from the `marketing` space to the `default` space:
[source,sh]
----
POST /s/marketing/api/spaces/_copy_saved_objects
$ curl -X POST "localhost:5601/s/marketing/api/spaces/_copy_saved_objects"
{
"objects": [{
"type": "visualization",
@ -273,9 +125,9 @@ POST /s/marketing/api/spaces/_copy_saved_objects
----
// KIBANA
The API returns the following result:
The API returns the following:
[source,js]
[source,sh]
----
{
"default": {

12
docs/api/spaces-management/delete.asciidoc
View file

@ -4,22 +4,20 @@
<titleabbrev>Delete space</titleabbrev>
++++
Delete a {kib} space.
experimental[] Delete a {kib} space.
experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
WARNING: When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone.
WARNING: When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone.
[[spaces-api-delete-request]]
==== Request
`DELETE /api/spaces/space/marketing`
`DELETE <kibana host>:<port>/api/spaces/space/marketing`
[[spaces-api-delete-errors-codes]]
==== Response codes
`204`::
`204`::
Indicates a successful call.
`404`::
Indicates that the request failed.

10
docs/api/spaces-management/get.asciidoc
View file

@ -4,14 +4,12 @@
<titleabbrev>Get space</titleabbrev>
++++
Retrieve a specified {kib} space.
experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
experimental[] Retrieve a specified {kib} space.
[[spaces-api-get-request]]
==== Request
`GET /api/spaces/space/marketing`
`GET <kibana host>:<port>/api/spaces/space/marketing`
[[spaces-api-get-response-codes]]
==== Response code
@ -24,7 +22,7 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"id": "marketing",
@ -35,4 +33,4 @@ The API returns the following:
"disabledFeatures": [],
"imageUrl": ""
}
--------------------------------------------------
--------------------------------------------------

8
docs/api/spaces-management/get_all.asciidoc
View file

@ -4,14 +4,12 @@
<titleabbrev>Get all spaces</titleabbrev>
++++
Retrieve all {kib} spaces.
experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
experimental[] Retrieve all {kib} spaces.
[[spaces-api-get-all-request]]
==== Request
`GET /api/spaces/space`
`GET <kibana host>:<port>/api/spaces/space`
[[spaces-api-get-all-response-codes]]
==== Response code
@ -24,7 +22,7 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
[
{

16
docs/api/spaces-management/post.asciidoc
View file

@ -4,14 +4,12 @@
<titleabbrev>Create space</titleabbrev>
++++
Create a {kib} space.
experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
experimental[] Create a {kib} space.
[[spaces-api-post-request]]
==== Request
`POST /api/spaces/space`
`POST <kibana host>:<port>/api/spaces/space`
[[spaces-api-post-request-body]]
==== Request body
@ -29,13 +27,13 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi
(Optional, string array) The list of disabled features for the space. To get a list of available feature IDs, use the <<features-api-get, Features API>>.
`initials`::
(Optional, string) Specifies the initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters.
(Optional, string) The initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters.
`color`::
(Optional, string) Specifies the hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.
(Optional, string) The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.
`imageUrl`::
(Optional, string) Specifies the data-url encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images.
(Optional, string) The data-URL encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images.
For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.
[[spaces-api-post-response-codes]]
@ -47,9 +45,9 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi
[[spaces-api-post-example]]
==== Example
[source,js]
[source,sh]
--------------------------------------------------
POST /api/spaces/space
$ curl -X POST "localhost:5601/api/spaces/space"
{
"id": "marketing",
"name": "Marketing",

26
docs/api/spaces-management/put.asciidoc
View file

@ -4,37 +4,35 @@
<titleabbrev>Update space</titleabbrev>
++++
Update an existing {kib} space.
experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
experimental[] Update an existing {kib} space.
[[spaces-api-put-api-request]]
==== Request
`PUT /api/spaces/space/<space_id>`
`PUT <kibana host>:<port>/api/spaces/space/<space_id>`
[[spaces-api-put-request-body]]
==== Request body
`id`::
`id`::
(Required, string) The space ID that is part of the {kib} URL when inside the space. You are unable to change the ID with the update operation.
`name`::
`name`::
(Required, string) The display name for the space.
`description`::
`description`::
(Optional, string) The description for the space.
`disabledFeatures`::
`disabledFeatures`::
(Optional, string array) The list of disabled features for the space. To get a list of available feature IDs, use the <<features-api-get, Features API>>.
`initials`::
`initials`::
(Optional, string) Specifies the initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters.
`color`::
`color`::
(Optional, string) Specifies the hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.
`imageUrl`::
`imageUrl`::
(Optional, string) Specifies the data-url encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images.
For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.
@ -43,13 +41,13 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi
`200`::
Indicates a successful call.
[[sample-api-example]]
==== Example
[source,js]
[source,sh]
--------------------------------------------------
PUT /api/spaces/space/marketing
$ curl -X PUT "localhost:5601/api/spaces/space/marketing"
{
"id": "marketing",
"name": "Marketing",

213
docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc
View file

@ -5,227 +5,80 @@
<titleabbrev>Resolve copy to space conflicts</titleabbrev>
++++
Overwrite specific saved objects that were returned as errors from the <<spaces-api-copy-saved-objects, Copy Saved Objects to Space API>>.
experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
////
Use the appropriate heading levels for your book.
Add anchors for each section.
FYI: The section titles use attributes in case those terms change.
////
experimental[] Overwrite saved objects that are returned as errors from the <<spaces-api-copy-saved-objects, copy saved objects to space API>>.
[[spaces-api-resolve-copy-saved-objects-conflicts-request]]
==== {api-request-title}
////
This section show the basic endpoint, without the body or optional parameters.
Variables should use <...> syntax.
If an API supports both PUT and POST, include both here.
////
`POST /api/spaces/_resolve_copy_saved_objects_errors`
`POST /s/<space_id>/api/spaces/_resolve_copy_saved_objects_errors`
`POST <kibana host>:<port>/api/spaces/_resolve_copy_saved_objects_errors`
`POST <kibana host>:<port>/s/<space_id>/api/spaces/_resolve_copy_saved_objects_errors`
[[spaces-api-resolve-copy-saved-objects-conflicts-prereqs]]
==== {api-prereq-title}
////
Optional list of prerequisites.
For example:
* A snapshot of an index created in 5.x can be restored to 6.x. You must...
* If the {es} {security-features} are enabled, you must have `write`, `monitor`,
and `manage_follow_index` index privileges...
////
* Executed the <<spaces-api-copy-saved-objects, Copy Saved Objects to Space API>>, which returned one or more `conflict` errors that you wish to resolve.
////
[[spaces-api-resolve-copy-saved-objects-conflicts-desc]]
==== {api-description-title}
Allows saved objects to be selectively overridden in the target spaces.
////
////
Add a more detailed description the context.
Link to related APIs if appropriate.
Guidelines for parameter documentation
***************************************
* Use a definition list.
* End each definition with a period.
* Include whether the parameter is Optional or Required and the data type.
* Include default values as the last sentence of the first paragraph.
* Include a range of valid values, if applicable.
* If the parameter requires a specific delimiter for multiple values, say so.
* If the parameter supports wildcards, ditto.
* For large or nested objects, consider linking to a separate definition list.
***************************************
////
Execute the <<spaces-api-copy-saved-objects,copy saved objects to space API>>, which returns the errors for you to resolve.
[[spaces-api-resolve-copy-saved-objects-conflicts-path-params]]
==== {api-path-parms-title}
////
A list of all the parameters within the path of the endpoint (before the query string (?)).
For example:
`<follower_index>`::
(Required, string) Name of the follower index
////
`space_id`::
(Optional, string) Identifies the source space from which saved objects will be copied. If `space_id` is not specified in the URL, the default space is used. Must be the same value that was used during the failed <<spaces-api-copy-saved-objects, Copy Saved Objects to Space>> operation.
////
[[spaces-api-resolve-copy-saved-objects-conflicts-request-params]]
==== {api-query-parms-title}
////
////
A list of the parameters in the query string of the endpoint (after the ?).
For example:
`wait_for_active_shards`::
(Optional, integer) Specifies the number of shards to wait on being active before
responding. A shard must be restored from the leader index being active.
Restoring a follower shard requires transferring all the remote Lucene segment
files to the follower index. The default is `0`, which means waiting on none of
the shards to be active.
////
(Optional, string) The ID of the space that contains the saved objects you want to copy. When `space_id` is unspecified in the URL, the default space is used. The `space_id` must be the same value used during the failed <<spaces-api-copy-saved-objects, copy saved objects to space API>> operation.
[[spaces-api-resolve-copy-saved-objects-conflicts-request-body]]
==== {api-request-body-title}
////
A list of the properties you can specify in the body of the request.
For example:
`remote_cluster`::
(Required, string) The <<modules-remote-clusters,remote cluster>> that contains
the leader index.
`leader_index`::
(Required, string) The name of the index in the leader cluster to follow.
////
`objects` ::
(Required, object array) The saved objects to copy. Must be the same value that was used during the failed <<spaces-api-copy-saved-objects, Copy Saved Objects to Space>> operation.
`type` :::
`objects`::
(Required, object array) The saved objects to copy. The `objects` must be the same values used during the failed <<spaces-api-copy-saved-objects, copy saved objects to space API>> operation.
`type`:::
(Required, string) The saved object type.
`id` :::
(Required, string) The saved object id.
`id`:::
(Required, string) The saved object ID.
`includeReferences` ::
(Optional, boolean) When set to `true`, all saved objects related to the specified saved objects will also be copied into the target spaces. You must set this to the same value that you used when executing the <<spaces-api-copy-saved-objects, Copy Saved Objects to Space API>>. The default value is `false`.
`includeReferences`::
(Optional, boolean) When set to `true`, all saved objects related to the specified saved objects are copied into the target spaces. The `includeReferences` must be the same values used during the failed <<spaces-api-copy-saved-objects, copy saved objects to space API>> operation. The default value is `false`.
`retries`::
(Required, object) The retry operations to attempt. Object keys represent the target space ids.
`<space_id>` :::
(Required, array) The the conflicts to resolve for the indicated `<space_id>`.
`type` ::::
(Required, object) The retry operations to attempt. Object keys represent the target space IDs.
`<space_id>`:::
(Required, array) The errors to resolve for the specified `<space_id>`.
`type`::::
(Required, string) The saved object type.
`id` ::::
(Required, string) The saved object id.
`overwrite` ::::
(Required, boolean) when set to `true`, the saved object from the source space (desigated by the <<spaces-api-resolve-copy-saved-objects-conflicts-path-params, `space_id` path parameter>>) will overwrite the the conflicting object in the destination space. When `false`, this does nothing.
`id`::::
(Required, string) The saved object ID.
`overwrite`::::
(Required, boolean) When set to `true`, the saved object from the source space (desigated by the <<spaces-api-resolve-copy-saved-objects-conflicts-path-params, `space_id` path parameter>>) overwrites the conflicting object in the destination space. When set to `false`, this does nothing.
[[spaces-api-resolve-copy-saved-objects-conflicts-response-body]]
==== {api-response-body-title}
////
Response body is only required for detailed responses.
For example:
`auto_follow_stats`::
(object) An object representing stats for the auto-follow coordinator. This
object consists of the following fields:
`auto_follow_stats.number_of_successful_follow_indices`:::
(long) the number of indices that the auto-follow coordinator successfully
followed
...
////
`<space_id>`::
(object) Specifies the dynamic keys that are included in the response. An object describing the result of the copy operation for this particular space.
(object) An object that describes the result of the copy operation for the space. Includes the dynamic keys in the response.
`success`:::
(boolean) Indicates if the copy operation was successful. Note that some objects may have been copied even if this is set to `false`. Consult the `successCount` and `errors` properties of the response for additional information.
(boolean) The copy operation was successful. When set to `false`, some objects may have been copied. For additional information, refer to the `successCount` and `errors` properties.
`successCount`:::
(number) The number of objects that were successfully copied.
(number) The number of objects that successfully copied.
`errors`:::
(Optional, array) Collection of any errors that were encountered during the copy operation. If any errors are reported, then the `success` flag will be set to `false`.
(Optional, array) The errors that occurred during the copy operation. When errors are reported, the `success` flag is set to `false`.
`id`::::
(string) The saved object id which failed to copy.
(string) The saved object ID that failed to copy.
`type`::::
(string) The type of saved object which failed to copy.
(string) The type of saved object that failed to copy.
`error`::::
(object) The error which caused the copy operation to fail.
(object) The error that caused the copy operation to fail.
`type`:::::
(string) Indicates the type of error. May be one of: `unsupported_type`, `missing_references`, `unknown`.
////
[[spaces-api-resolve-copy-saved-objects-conflicts-response-codes]]
==== {api-response-codes-title}
////
////
Response codes are only required when needed to understand the response body.
For example:
`200`::
Indicates all listed indices or index aliases exist.
`404`::
Indicates one or more listed indices or index aliases **do not** exist.
////
(string) The type of error. For example, `unsupported_type`, `missing_references`, or `unknown`.
[[spaces-api-resolve-copy-saved-objects-conflicts-example]]
==== {api-examples-title}
////
Optional brief example.
Use an 'Examples' heading if you include multiple examples.
Overwrite an index pattern in the `marketing` space, and a visualization in the `sales` space:
[source,js]
[source,sh]
----
PUT /follower_index/_ccr/follow?wait_for_active_shards=1
{
"remote_cluster" : "remote_cluster",
"leader_index" : "leader_index",
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}
----
// CONSOLE
// TEST[setup:remote_cluster_and_leader_index]
The API returns the following result:
[source,js]
----
{
"follow_index_created" : true,
"follow_index_shards_acked" : true,
"index_following_started" : true
}
----
// TESTRESPONSE
////
The following example overwrites an index pattern in the marketing space, and a visualization in the sales space.
[source,js]
----
POST api/spaces/_resolve_copy_saved_objects_errors
$ curl -X POST "localhost:5601/api/spaces/_resolve_copy_saved_objects_errors"
{
"objects": [{
"type": "dashboard",
@ -248,9 +101,9 @@ POST api/spaces/_resolve_copy_saved_objects_errors
----
// KIBANA
The API returns the following result:
The API returns the following:
[source,js]
[source,sh]
----
{
"marketing": {

4
docs/api/upgrade-assistant.asciidoc
View file

@ -2,7 +2,7 @@
[[upgrade-assistant-api]]
== Upgrade assistant APIs
Check the upgrade status of your Elasticsearch cluster and reindex indices that were created in the previous major version. The assistant helps you prepare for the next major version of Elasticsearch.
Check the upgrade status of your {es} cluster and reindex indices that were created in the previous major version. The assistant helps you prepare for the next major version of {es}.
The following upgrade assistant APIs are available:
@ -16,7 +16,7 @@ The following upgrade assistant APIs are available:
* <<check-reindex-status, Check reindex status API>> to check the status of the reindex operation
* <<cancel-reindex, Cancel reindex API>> to cancel reindexes that are waiting for the Elasticsearch reindex task to complete
* <<cancel-reindex, Cancel reindex API>> to cancel reindexes that are waiting for the {es} reindex task to complete
include::upgrade-assistant/status.asciidoc[]
include::upgrade-assistant/reindexing.asciidoc[]

6
docs/api/upgrade-assistant/cancel_reindex.asciidoc
View file

@ -4,14 +4,14 @@
<titleabbrev>Cancel reindex</titleabbrev>
++++
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
experimental[] Cancel reindexes that are waiting for the {es} reindex task to complete. For example, `lastCompletedStep` set to `40`.
Cancel reindexes that are waiting for the Elasticsearch reindex task to complete. For example, `lastCompletedStep` set to `40`.
[[cancel-reindex-request]]
==== Request
`POST /api/upgrade_assistant/reindex/myIndex/cancel`
`POST <kibana host>:<port>/api/upgrade_assistant/reindex/myIndex/cancel`
[[cancel-reindex-response-codes]]
==== Response codes
@ -24,7 +24,7 @@ Cancel reindexes that are waiting for the Elasticsearch reindex task to complete
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"acknowledged": true

65
docs/api/upgrade-assistant/check_reindex_status.asciidoc
View file

@ -4,27 +4,27 @@
<titleabbrev>Check reindex status</titleabbrev>
++++
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
experimental[] Check the status of the reindex operation.
Check the status of the reindex operation.
[[check-reindex-status-request]]
==== Request
`GET /api/upgrade_assistant/reindex/myIndex`
`GET <kibana host>:<port>/api/upgrade_assistant/reindex/myIndex`
[[check-reindex-status-response-codes]]
==== Response codes
`200`::
Indicates a successful call.
[[check-reindex-status-example]]
==== Example
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"reindexOp": {
@ -53,59 +53,58 @@ The API returns the following:
[[status-code]]
==== Status codes
`0`::
`0`::
In progress
`1`::
`1`::
Completed
`2`::
`2`::
Failed
`3`::
`3`::
Paused
NOTE: If the {kib} node that started the reindex is shutdown or restarted, the reindex goes into a paused state after some time.
To resume the reindex, you must submit a new POST request to the `/api/upgrade_assistant/reindex/<indexName>` endpoint.
`4`::
`4`::
Cancelled
[[step-code]]
==== Step codes
`0`::
`0`::
The reindex operation has been created in Kibana.
`10`::
`10`::
The index group services stopped. Only applies to some system indices.
`20`::
The index is set to `readonly`.
`30`::
`20`::
The index is set to `readonly`.
`30`::
The new destination index has been created.
`40`::
`40`::
The reindex task in Elasticsearch has started.
`50`::
`50`::
The reindex task in Elasticsearch has completed.
`60`::
`60`::
Aliases were created to point to the new index, and the old index has been deleted.
`70`::
`70`::
The index group services have resumed. Only applies to some system indices.
[[warning-code]]
==== Warning codes
`0`::
`0`::
Specifies to remove the `_all` meta field.
`1`::
Specifies to convert any coerced boolean values in the source document. For example, `yes`, `1`, and `off`.
`2`::
Specifies to convert documents to support Elastic Common Schema. Only applies to APM indices created in 6.x.
`1`::
Specifies to convert any coerced boolean values in the source document. For example, `yes`, `1`, and `off`.
`2`::
Specifies to convert documents to support Elastic Common Schema. Only applies to APM indices created in 6.x.

18
docs/api/upgrade-assistant/reindexing.asciidoc
View file

@ -4,14 +4,14 @@
<titleabbrev>Start or resume reindex</titleabbrev>
++++
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
experimental[] Start a new reindex or resume a paused reindex.
Start a new reindex or resume a paused reindex.
[[start-resume-reindex-request]]
==== Request
`POST /api/upgrade_assistant/reindex/myIndex`
`POST <kibana host>:<port>/api/upgrade_assistant/reindex/myIndex`
[[start-resume-reindex-codes]]
==== Response code
@ -24,7 +24,7 @@ Start a new reindex or resume a paused reindex.
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"indexName": ".ml-state",
@ -37,9 +37,9 @@ The API returns the following:
}
--------------------------------------------------
<1> Name of the new index that is being created.
<2> Current status of the reindex. For details, see <<status-code,Status codes>>.
<3> Last successfully completed step of the reindex. For details, see <<step-code,Step codes>> table.
<4> Task ID of the reindex task in Elasticsearch. Only present if reindexing has started.
<5> Percentage of how far the reindexing task in Elasticsearch has progressed, in decimal from from 0 to 1.
<6> Error that caused the reindex to fail, if it failed.
<1> The name of the new index.
<2> The reindex status. For more information, refer to <<status-code,Status codes>>.
<3> The last successfully completed step of the reindex. For more information, refer to <<step-code,Step codes>>.
<4> The task ID of the reindex task in {es}. Appears when the reindexing starts.
<5> The progress of the reindexing task in {es}. Appears in decimal form, from 0 to 1.
<6> The error that caused the reindex to fail, if it failed.

6
docs/api/upgrade-assistant/status.asciidoc
View file

@ -4,14 +4,14 @@
<titleabbrev>Upgrade readiness status</titleabbrev>
++++
experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
experimental[] Check the status of your cluster.
Check the status of your cluster.
[[upgrade-assistant-api-status-request]]
==== Request
`GET /api/upgrade_assistant/status`
`GET <kibana host>:<port>/api/upgrade_assistant/status`
[[upgrade-assistant-api-status-response-codes]]
==== Response codes
@ -24,7 +24,7 @@ Check the status of your cluster.
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"readyForUpgrade": false,

16
docs/api/url-shortening.asciidoc
View file

@ -12,18 +12,18 @@ Short URLs are designed to make sharing {kib} URLs easier.
[[url-shortening-api-request]]
==== Request
`POST /api/shorten_url`
`POST <kibana host>:<port>/api/shorten_url`
[[url-shortening-api-request-body]]
==== Request body
`url`::
(Required, string) The {kib} URL that you want to shorten, Relative to `/app/kibana`.
(Required, string) The {kib} URL that you want to shorten, relative to `/app/kibana`.
[[url-shortening-api-response-body]]
==== Response body
urlId:: A top level property that contains the shortened URL token for the provided request body.
urlId:: A top-level property that contains the shortened URL token for the provided request body.
[[url-shortening-api-codes]]
==== Response code
@ -31,21 +31,21 @@ urlId:: A top level property that contains the shortened URL token for the provi
`200`::
Indicates a successful call.
[[url-shortening-api-example]]
[[url-shortening-api-example]]
==== Example
[source,js]
[source,sh]
--------------------------------------------------
POST api/shorten_url
$ curl -X POST "localhost:5601/api/shorten_url"
{
"url": "/app/kibana#/dashboard?_g=()&_a=(description:'',filters:!(),fullScreenMode:!f,options:(hidePanelTitles:!f,useMargins:!t),panels:!((embeddableConfig:(),gridData:(h:15,i:'1',w:24,x:0,y:0),id:'8f4d0c00-4c86-11e8-b3d7-01146121b73d',panelIndex:'1',type:visualization,version:'7.0.0-alpha1')),query:(language:lucene,query:''),timeRestore:!f,title:'New%20Dashboard',viewMode:edit)"
}
--------------------------------------------------
// KIBANA
The API returns the following result:
The API returns the following:
[source,js]
[source,sh]
--------------------------------------------------
{
"urlId": "f73b295ff92718b26bc94edac766d8e3"

5
docs/api/using-api.asciidoc
View file

@ -33,6 +33,7 @@ For example, the following `curl` command exports a dashboard:
--
curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c"
--
// KIBANA
[float]
[[api-request-headers]]
@ -43,14 +44,14 @@ For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsr
`kbn-xsrf: true`::
By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios:
* The API endpoint uses the `GET` or `HEAD` methods
* The API endpoint uses the `GET` or `HEAD` operations
* The path is whitelisted using the <<settings, `server.xsrf.whitelist`>> setting
* XSRF protections are disabled using the `server.xsrf.disableProtection` setting
`Content-Type: application/json`::
Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON. Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header.
Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON. Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header.
Request header example: