diff --git a/docs/api/dashboard-api.asciidoc b/docs/api/dashboard-api.asciidoc new file mode 100644 index 0000000000000..50c2abc975763 --- /dev/null +++ b/docs/api/dashboard-api.asciidoc @@ -0,0 +1,17 @@ +[[dashboard-api]] +== Import and export dashboard APIs + +Import and export dashboards with the corresponding saved objects, such as visualizations, saved +searches, and index patterns. + +WARNING: Do not write documents directly to the `.kibana` index. When you write directly +to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions. + +The following import and export dashboard APIs are available: + +* <> to import dashboards and corresponding saved objects + +* <> to export dashboards and corresponding saved objects + +include::dashboard/import-dashboard.asciidoc[] +include::dashboard/export-dashboard.asciidoc[] \ No newline at end of file diff --git a/docs/api/dashboard-import.asciidoc b/docs/api/dashboard-import.asciidoc deleted file mode 100644 index 19eb6f2a446b5..0000000000000 --- a/docs/api/dashboard-import.asciidoc +++ /dev/null @@ -1,14 +0,0 @@ -[[dashboard-import-api]] -== Dashboard import and export APIs - -Import and export dashboards with the corresponding saved objects, such as visualizations, saved -searches, and index patterns. - -WARNING: Do not write documents directly to the `.kibana` index. When you write directly -to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions. - -* <> -* <> - -include::dashboard-import/import.asciidoc[] -include::dashboard-import/export.asciidoc[] diff --git a/docs/api/dashboard-import/export.asciidoc b/docs/api/dashboard/export-dashboard.asciidoc similarity index 85% rename from docs/api/dashboard-import/export.asciidoc rename to docs/api/dashboard/export-dashboard.asciidoc index 13a0ffe8febeb..7858b69d44c79 100644 --- a/docs/api/dashboard-import/export.asciidoc +++ b/docs/api/dashboard/export-dashboard.asciidoc @@ -1,7 +1,7 @@ [[dashboard-api-export]] === Export dashboard API ++++ -Dashboard export +Export dashboard ++++ experimental[] Export dashboards and corresponding saved objects. @@ -21,7 +21,7 @@ experimental[] Export dashboards and corresponding saved objects. ==== Response body `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 <>. + (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-api-export-codes]] ==== Response code @@ -39,4 +39,4 @@ GET api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c -------------------------------------------------- // KIBANA -<1> In this example, `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c` is the dashboard ID. +<1> The dashboard ID is `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`. \ No newline at end of file diff --git a/docs/api/dashboard-import/import.asciidoc b/docs/api/dashboard/import-dashboard.asciidoc similarity index 99% rename from docs/api/dashboard-import/import.asciidoc rename to docs/api/dashboard/import-dashboard.asciidoc index 9ff84abb51c8e..0c6ea2bcf5933 100644 --- a/docs/api/dashboard-import/import.asciidoc +++ b/docs/api/dashboard/import-dashboard.asciidoc @@ -1,4 +1,4 @@ -[[dashboard-import-api-import]] +[[dashboard-import-api]] === Import dashboard API ++++ Import dashboard diff --git a/docs/api/features.asciidoc b/docs/api/features.asciidoc index 798f2be3d7212..7928f7f34aad7 100644 --- a/docs/api/features.asciidoc +++ b/docs/api/features.asciidoc @@ -1,9 +1,217 @@ [role="xpack"] -[[features-api]] -== Features API +[[features-api-get]] +== Get features API -View information about the available features in {kib}. Features are used by spaces and security to refine and secure access to {kib}. +experimental[] Retrieves all {kib} features. Features are used by spaces and security to refine and secure access to {kib}. -* <> +[float] +[[features-api-get-request]] +=== Request -include::features/get.asciidoc[] +`GET /api/features` + +[float] +[[features-api-get-codes]] +=== Response code + +`200`:: + Indicates a successful call. + +[float] +[[features-api-get-example]] +=== Example + +The API returns the following: + +[source,js] +-------------------------------------------------- + { + "id": "discover", + "name": "Discover", + "icon": "discoverApp", + "navLinkId": "kibana:discover", + "app": [ + "kibana" + ], + "catalogue": [ + "discover" + ], + "privileges": { + "all": { + "savedObject": { + "all": [ + "search", + "url" + ], + "read": [ + "config", + "index-pattern" + ] + }, + "ui": [ + "show", + "createShortUrl", + "save" + ] + }, + "read": { + "savedObject": { + "all": [], + "read": [ + "config", + "index-pattern", + "search", + "url" + ] + }, + "ui": [ + "show" + ] + } + } + }, + { + "id": "visualize", + "name": "Visualize", + "icon": "visualizeApp", + "navLinkId": "kibana:visualize", + "app": [ + "kibana" + ], + "catalogue": [ + "visualize" + ], + "privileges": { + "all": { + "savedObject": { + "all": [ + "visualization", + "url" + ], + "read": [ + "config", + "index-pattern", + "search" + ] + }, + "ui": [ + "show", + "createShortUrl", + "delete", + "save" + ] + }, + "read": { + "savedObject": { + "all": [], + "read": [ + "config", + "index-pattern", + "search", + "visualization" + ] + }, + "ui": [ + "show" + ] + } + } + }, + { + "id": "dashboard", + "name": "Dashboard", + "icon": "dashboardApp", + "navLinkId": "kibana:dashboard", + "app": [ + "kibana" + ], + "catalogue": [ + "dashboard" + ], + "privileges": { + "all": { + "savedObject": { + "all": [ + "dashboard", + "url" + ], + "read": [ + "config", + "index-pattern", + "search", + "visualization", + "timelion-sheet", + "canvas-workpad" + ] + }, + "ui": [ + "createNew", + "show", + "showWriteControls" + ] + }, + "read": { + "savedObject": { + "all": [], + "read": [ + "config", + "index-pattern", + "search", + "visualization", + "timelion-sheet", + "canvas-workpad", + "dashboard" + ] + }, + "ui": [ + "show" + ] + } + } + }, + { + "id": "dev_tools", + "name": "Dev Tools", + "icon": "devToolsApp", + "navLinkId": "kibana:dev_tools", + "app": [ + "kibana" + ], + "catalogue": [ + "console", + "searchprofiler", + "grokdebugger" + ], + "privileges": { + "all": { + "api": [ + "console" + ], + "savedObject": { + "all": [], + "read": [ + "config" + ] + }, + "ui": [ + "show" + ] + }, + "read": { + "api": [ + "console" + ], + "savedObject": { + "all": [], + "read": [ + "config" + ] + }, + "ui": [ + "show" + ] + } + }, + "privilegesTooltip": "User should also be granted the appropriate Elasticsearch cluster and index privileges" + }, +-------------------------------------------------- diff --git a/docs/api/features/get.asciidoc b/docs/api/features/get.asciidoc deleted file mode 100644 index fc2c0446d82a8..0000000000000 --- a/docs/api/features/get.asciidoc +++ /dev/null @@ -1,216 +0,0 @@ -[[features-api-get]] -=== Get features API -++++ -Get features -++++ - -experimental[] Retrieves all {kib} features. - -[[features-api-get-request]] -==== Request - -`GET /api/features` - -[[features-api-get-codes]] -==== Response code - -`200`:: - Indicates a successful call. - -[[features-api-get-example]] -==== Example - -The API returns the following: - -[source,js] --------------------------------------------------- - { - "id": "discover", - "name": "Discover", - "icon": "discoverApp", - "navLinkId": "kibana:discover", - "app": [ - "kibana" - ], - "catalogue": [ - "discover" - ], - "privileges": { - "all": { - "savedObject": { - "all": [ - "search", - "url" - ], - "read": [ - "config", - "index-pattern" - ] - }, - "ui": [ - "show", - "createShortUrl", - "save" - ] - }, - "read": { - "savedObject": { - "all": [], - "read": [ - "config", - "index-pattern", - "search", - "url" - ] - }, - "ui": [ - "show" - ] - } - } - }, - { - "id": "visualize", - "name": "Visualize", - "icon": "visualizeApp", - "navLinkId": "kibana:visualize", - "app": [ - "kibana" - ], - "catalogue": [ - "visualize" - ], - "privileges": { - "all": { - "savedObject": { - "all": [ - "visualization", - "url" - ], - "read": [ - "config", - "index-pattern", - "search" - ] - }, - "ui": [ - "show", - "createShortUrl", - "delete", - "save" - ] - }, - "read": { - "savedObject": { - "all": [], - "read": [ - "config", - "index-pattern", - "search", - "visualization" - ] - }, - "ui": [ - "show" - ] - } - } - }, - { - "id": "dashboard", - "name": "Dashboard", - "icon": "dashboardApp", - "navLinkId": "kibana:dashboard", - "app": [ - "kibana" - ], - "catalogue": [ - "dashboard" - ], - "privileges": { - "all": { - "savedObject": { - "all": [ - "dashboard", - "url" - ], - "read": [ - "config", - "index-pattern", - "search", - "visualization", - "timelion-sheet", - "canvas-workpad" - ] - }, - "ui": [ - "createNew", - "show", - "showWriteControls" - ] - }, - "read": { - "savedObject": { - "all": [], - "read": [ - "config", - "index-pattern", - "search", - "visualization", - "timelion-sheet", - "canvas-workpad", - "dashboard" - ] - }, - "ui": [ - "show" - ] - } - } - }, - { - "id": "dev_tools", - "name": "Dev Tools", - "icon": "devToolsApp", - "navLinkId": "kibana:dev_tools", - "app": [ - "kibana" - ], - "catalogue": [ - "console", - "searchprofiler", - "grokdebugger" - ], - "privileges": { - "all": { - "api": [ - "console" - ], - "savedObject": { - "all": [], - "read": [ - "config" - ] - }, - "ui": [ - "show" - ] - }, - "read": { - "api": [ - "console" - ], - "savedObject": { - "all": [], - "read": [ - "config" - ] - }, - "ui": [ - "show" - ] - } - }, - "privilegesTooltip": "User should also be granted the appropriate Elasticsearch cluster and index privileges" - }, --------------------------------------------------- diff --git a/docs/api/logstash-configuration-management.asciidoc b/docs/api/logstash-configuration-management.asciidoc index e53218ec439aa..fbb45095c214b 100644 --- a/docs/api/logstash-configuration-management.asciidoc +++ b/docs/api/logstash-configuration-management.asciidoc @@ -6,12 +6,19 @@ Programmatically integrate with the Logstash configuration management feature. 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. -* <> -* <> -* <> -* <> - -include::logstash-configuration-management/create.asciidoc[] -include::logstash-configuration-management/retrieve.asciidoc[] -include::logstash-configuration-management/delete.asciidoc[] -include::logstash-configuration-management/list.asciidoc[] \ No newline at end of file +The following Logstash configuration management APIs are available: + +* <> to delete a centrally-managed Logstash pipeline + +* <> to list all centrally-managed Logstash pipelines + +* <> to create a centrally-managed Logstash pipeline, or update an existing pipeline + +* <> to retrieve a centrally-managed Logstash pipeline + +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[] + + diff --git a/docs/api/logstash-configuration-management/create.asciidoc b/docs/api/logstash-configuration-management/create-logstash.asciidoc similarity index 96% rename from docs/api/logstash-configuration-management/create.asciidoc rename to docs/api/logstash-configuration-management/create-logstash.asciidoc index d6fbfd4947bab..38e0ee12a0ebf 100644 --- a/docs/api/logstash-configuration-management/create.asciidoc +++ b/docs/api/logstash-configuration-management/create-logstash.asciidoc @@ -1,8 +1,7 @@ -[role="xpack"] [[logstash-configuration-management-api-create]] === Create Logstash pipeline API ++++ -Create pipeline +Create Logstash pipeline ++++ experimental[] Create a centrally-managed Logstash pipeline, or update an existing pipeline. diff --git a/docs/api/logstash-configuration-management/delete.asciidoc b/docs/api/logstash-configuration-management/delete-pipeline.asciidoc similarity index 97% rename from docs/api/logstash-configuration-management/delete.asciidoc rename to docs/api/logstash-configuration-management/delete-pipeline.asciidoc index c5aadb495ee15..15d44034b46fe 100644 --- a/docs/api/logstash-configuration-management/delete.asciidoc +++ b/docs/api/logstash-configuration-management/delete-pipeline.asciidoc @@ -1,4 +1,3 @@ -[role="xpack"] [[logstash-configuration-management-api-delete]] === Delete Logstash pipeline API ++++ @@ -31,4 +30,5 @@ experimental[] Delete a centrally-managed Logstash pipeline. -------------------------------------------------- DELETE api/logstash/pipeline/hello-world -------------------------------------------------- -// KIBANA \ No newline at end of file +// KIBANA + diff --git a/docs/api/logstash-configuration-management/list.asciidoc b/docs/api/logstash-configuration-management/list-pipeline.asciidoc similarity index 84% rename from docs/api/logstash-configuration-management/list.asciidoc rename to docs/api/logstash-configuration-management/list-pipeline.asciidoc index a11199d7b8dbc..7140c35d89853 100644 --- a/docs/api/logstash-configuration-management/list.asciidoc +++ b/docs/api/logstash-configuration-management/list-pipeline.asciidoc @@ -1,4 +1,3 @@ -[role="xpack"] [[logstash-configuration-management-api-list]] === List Logstash pipeline API ++++ @@ -36,4 +35,4 @@ The API returns the following: } -------------------------------------------------- -<1> The `username` property may or may not be present, depending on if security was enabled 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. \ No newline at end of file diff --git a/docs/api/logstash-configuration-management/retrieve.asciidoc b/docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc similarity index 85% rename from docs/api/logstash-configuration-management/retrieve.asciidoc rename to docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc index 3bc5f13c56ac1..93a1ec3aa1da5 100644 --- a/docs/api/logstash-configuration-management/retrieve.asciidoc +++ b/docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc @@ -1,11 +1,10 @@ -[role="xpack"] [[logstash-configuration-management-api-retrieve]] === Retrieve pipeline API ++++ Retrieve pipeline ++++ -experimental[] Retrieves a centrally-managed Logstash pipeline. +experimental[] Retrieve a centrally-managed Logstash pipeline. [[logstash-configuration-management-api-retrieve-request]] ==== Request @@ -34,4 +33,4 @@ The API returns the following: "queue.type": "persistent" } } --------------------------------------------------- +-------------------------------------------------- \ No newline at end of file diff --git a/docs/api/role-management.asciidoc b/docs/api/role-management.asciidoc index 622d26571cd6e..482d1a9b3cdd3 100644 --- a/docs/api/role-management.asciidoc +++ b/docs/api/role-management.asciidoc @@ -1,15 +1,20 @@ [role="xpack"] [[role-management-api]] -== Kibana role management APIs +== {kib} role management APIs Manage the roles that grant <>. 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: + +* <> to create a new {kib} role, or update the attributes of an existing role + +* <> to retrieve all {kib} roles + +* <> to retrieve a specific role + +* <> to delete a {kib} role include::role-management/put.asciidoc[] include::role-management/get.asciidoc[] diff --git a/docs/api/role-management/delete.asciidoc b/docs/api/role-management/delete.asciidoc index eb8ab183576fd..acf2e4a3e3f1f 100644 --- a/docs/api/role-management/delete.asciidoc +++ b/docs/api/role-management/delete.asciidoc @@ -4,7 +4,7 @@ Delete role ++++ -Deletes a {kib} role. +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."] diff --git a/docs/api/role-management/get-all.asciidoc b/docs/api/role-management/get-all.asciidoc index b318fecb3b4e1..4a3dbd7734d3a 100644 --- a/docs/api/role-management/get-all.asciidoc +++ b/docs/api/role-management/get-all.asciidoc @@ -4,7 +4,7 @@ Get all roles ++++ -Retrieves all {kib} roles. +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."] diff --git a/docs/api/role-management/get.asciidoc b/docs/api/role-management/get.asciidoc index 34d7c256bd564..44423b01abe5b 100644 --- a/docs/api/role-management/get.asciidoc +++ b/docs/api/role-management/get.asciidoc @@ -4,7 +4,7 @@ Get specific role ++++ -Retrieves a specific role. +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."] diff --git a/docs/api/role-management/put.asciidoc b/docs/api/role-management/put.asciidoc index af7544f8ecb46..67ec15892afe4 100644 --- a/docs/api/role-management/put.asciidoc +++ b/docs/api/role-management/put.asciidoc @@ -4,7 +4,7 @@ Create or update role ++++ -Creates a new {kib} role, or updates the attributes of an existing role. {kib} roles are stored in the +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."] @@ -40,7 +40,7 @@ To use the create or update role API, you must have the `manage_security` cluste `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 <>. + To retrieve a list of available features, use the <>. `spaces` ::: (list) The spaces to apply the privileges to. diff --git a/docs/api/saved-objects.asciidoc b/docs/api/saved-objects.asciidoc index 6c7e015f9f81c..a4e9fa32f8a5c 100644 --- a/docs/api/saved-objects.asciidoc +++ b/docs/api/saved-objects.asciidoc @@ -6,16 +6,27 @@ Manage {kib} saved objects, including dashboards, visualizations, index patterns WARNING: Do not write documents directly to the `.kibana` index. When you write directly to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions. -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +The following saved objects APIs are available: + +* <> to retrieve a single {kib} saved object by ID + +* <> to retrieve multiple {kib} saved objects by ID + +* <> to retrieve a paginated set of {kib} saved objects by various conditions + +* <> to create {kib} saved objects + +* <> to create multiple {kib} saved objects + +* <> to update the attributes for existing {kib} saved objects + +* <> to remove {kib} saved objects + +* <> to retrieve sets of saved objects that you want to import into {kib} + +* <> to create sets of {kib} saved objects from a file created by the export API + +* <> to resolve errors from the import API include::saved-objects/get.asciidoc[] include::saved-objects/bulk_get.asciidoc[] diff --git a/docs/api/saved-objects/bulk_create.asciidoc b/docs/api/saved-objects/bulk_create.asciidoc index de66af78f5bd2..ca8cc0f287015 100644 --- a/docs/api/saved-objects/bulk_create.asciidoc +++ b/docs/api/saved-objects/bulk_create.asciidoc @@ -1,7 +1,7 @@ [[saved-objects-api-bulk-create]] === Bulk create saved objects API ++++ -Bulk create objects +Bulk create saved objects ++++ experimental[] Create multiple {kib} saved objects. diff --git a/docs/api/saved-objects/bulk_get.asciidoc b/docs/api/saved-objects/bulk_get.asciidoc index 454572254e5c5..4f2cbcb980f82 100644 --- a/docs/api/saved-objects/bulk_get.asciidoc +++ b/docs/api/saved-objects/bulk_get.asciidoc @@ -4,7 +4,7 @@ Bulk get objects ++++ -experimental[] Retrieves multiple {kib} saved objects by ID. +experimental[] Retrieve multiple {kib} saved objects by ID. [[saved-objects-api-bulk-get-request]] ==== Request diff --git a/docs/api/saved-objects/create.asciidoc b/docs/api/saved-objects/create.asciidoc index 1969d9b9ffbd8..fecc3f3732f2a 100644 --- a/docs/api/saved-objects/create.asciidoc +++ b/docs/api/saved-objects/create.asciidoc @@ -1,10 +1,10 @@ [[saved-objects-api-create]] -=== Create saved object API +=== Create saved objects API ++++ -Create object +Create saved objects ++++ -experimental[] Create a {kib} saved object. +experimental[] Create {kib} saved objects. [[saved-objects-api-create-request]] ==== Request diff --git a/docs/api/saved-objects/delete.asciidoc b/docs/api/saved-objects/delete.asciidoc index 84381e3946adc..4a96cf554f784 100644 --- a/docs/api/saved-objects/delete.asciidoc +++ b/docs/api/saved-objects/delete.asciidoc @@ -4,7 +4,7 @@ Delete object ++++ -experimental[] Remove a {kib} saved object. +experimental[] Remove {kib} saved objects. WARNING: Once you delete a saved object, _it cannot be recovered_. diff --git a/docs/api/saved-objects/export.asciidoc b/docs/api/saved-objects/export.asciidoc index e6c0adf2128ba..ee56e6bad75c8 100644 --- a/docs/api/saved-objects/export.asciidoc +++ b/docs/api/saved-objects/export.asciidoc @@ -4,7 +4,7 @@ Export objects ++++ -experimental[] Retrieve a set of saved objects that you want to import into {kib}. +experimental[] Retrieve sets of saved objects that you want to import into {kib}. [[saved-objects-api-export-request]] ==== Request diff --git a/docs/api/saved-objects/import.asciidoc b/docs/api/saved-objects/import.asciidoc index af384718051c0..0331f23284352 100644 --- a/docs/api/saved-objects/import.asciidoc +++ b/docs/api/saved-objects/import.asciidoc @@ -4,7 +4,7 @@ Import objects ++++ -experimental[] Create a set of {kib} saved objects from a file created by the export API. +experimental[] Create sets of {kib} saved objects from a file created by the export API. [[saved-objects-api-import-request]] ==== Request diff --git a/docs/api/saved-objects/update.asciidoc b/docs/api/saved-objects/update.asciidoc index a1e7be37e1c4a..5c4bb98d09228 100644 --- a/docs/api/saved-objects/update.asciidoc +++ b/docs/api/saved-objects/update.asciidoc @@ -4,7 +4,7 @@ Update object ++++ -experimental[] Update the attributes for an existing {kib} saved object. +experimental[] Update the attributes for existing {kib} saved objects. [[saved-objects-api-update-request]] ==== Request diff --git a/docs/api/spaces-management.asciidoc b/docs/api/spaces-management.asciidoc index bb949667963b7..2e3b9abec9120 100644 --- a/docs/api/spaces-management.asciidoc +++ b/docs/api/spaces-management.asciidoc @@ -1,16 +1,24 @@ [role="xpack"] [[spaces-api]] -== Kibana Spaces APIs +== {kib} spaces APIs Manage your {kib} spaces. -* <> -* <> -* <> -* <> -* <> -* <> -* <> +The following {kib} spaces APIs are available: + +* <> to create a {kib} space + +* <> to update an existing {kib} space + +* <> to retrieve a specified {kib} space + +* <> to retrieve all {kib} spaces + +* <> to delete a {kib} space + +* <> to copy saved objects between spaces + +* <> to overwrite saved objects returned as errors from the copy saved objects to space API include::spaces-management/post.asciidoc[] include::spaces-management/put.asciidoc[] diff --git a/docs/api/spaces-management/delete.asciidoc b/docs/api/spaces-management/delete.asciidoc index 64b90f3d49dad..c66307ea3070f 100644 --- a/docs/api/spaces-management/delete.asciidoc +++ b/docs/api/spaces-management/delete.asciidoc @@ -4,7 +4,7 @@ Delete space ++++ -Deletes a {kib} space. +Delete a {kib} space. experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] diff --git a/docs/api/spaces-management/get.asciidoc b/docs/api/spaces-management/get.asciidoc index 569117e866d2a..49119d7602b20 100644 --- a/docs/api/spaces-management/get.asciidoc +++ b/docs/api/spaces-management/get.asciidoc @@ -4,7 +4,7 @@ Get space ++++ -Retrieves a specified {kib} space. +Retrieve a specified {kib} space. experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] diff --git a/docs/api/spaces-management/get_all.asciidoc b/docs/api/spaces-management/get_all.asciidoc index 6f683b864e145..4ae67a0dcca8b 100644 --- a/docs/api/spaces-management/get_all.asciidoc +++ b/docs/api/spaces-management/get_all.asciidoc @@ -4,7 +4,7 @@ Get all spaces ++++ -Retrieves all {kib} spaces. +Retrieve all {kib} spaces. experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] diff --git a/docs/api/spaces-management/post.asciidoc b/docs/api/spaces-management/post.asciidoc index ea8311ea8213f..d8c194d8dc2b5 100644 --- a/docs/api/spaces-management/post.asciidoc +++ b/docs/api/spaces-management/post.asciidoc @@ -4,7 +4,7 @@ Create space ++++ -Creates a {kib} space. +Create a {kib} space. experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] diff --git a/docs/api/spaces-management/put.asciidoc b/docs/api/spaces-management/put.asciidoc index 113fdbce6a90a..586818707c76f 100644 --- a/docs/api/spaces-management/put.asciidoc +++ b/docs/api/spaces-management/put.asciidoc @@ -4,7 +4,7 @@ Update space ++++ -Updates an existing {kib} space. +Update an existing {kib} space. experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] diff --git a/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc b/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc index bb82c07e765cb..7b52125599c05 100644 --- a/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc +++ b/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc @@ -5,7 +5,7 @@ Resolve copy to space conflicts ++++ -Overwrites specific saved objects that were returned as errors from the <>. +Overwrite specific saved objects that were returned as errors from the <>. experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] diff --git a/docs/api/upgrade-assistant.asciidoc b/docs/api/upgrade-assistant.asciidoc index 3cb256c337175..b524307c0f273 100644 --- a/docs/api/upgrade-assistant.asciidoc +++ b/docs/api/upgrade-assistant.asciidoc @@ -4,10 +4,15 @@ 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. -* <> -* <> -* <> -* <> +The following upgrade assistant APIs are available: + +* <> to check the status of your cluster + +* <> to start a new reindex or resume a paused reindex + +* <> to check the status of the reindex operation + +* <> to cancel reindexes that are waiting for the Elasticsearch reindex task to complete include::upgrade-assistant/status.asciidoc[] include::upgrade-assistant/reindexing.asciidoc[] diff --git a/docs/api/url-shortening.asciidoc b/docs/api/url-shortening.asciidoc index e98210e92d94a..8bc701a3d5d12 100644 --- a/docs/api/url-shortening.asciidoc +++ b/docs/api/url-shortening.asciidoc @@ -1,11 +1,57 @@ [[url-shortening-api]] -== URL shortening API +=== Shorten URL API +++++ +Shorten URL +++++ -{kib} URLs contain the state of the application, which makes them long and cumbersome. +experimental[] Convert a {kib} URL into a token. {kib} URLs contain the state of the application, which makes them long and cumbersome. Internet Explorer has URL length restrictions, and some wiki and markup parsers don't do well with the full-length version of the {kib} URL. Short URLs are designed to make sharing {kib} URLs easier. -* <> +[[url-shortening-api-request]] +==== Request -include::url_shortening/shorten_url.asciidoc[] +`POST /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`. + +[[url-shortening-api-response-body]] +==== Response body + +urlId:: A top level property that contains the shortened URL token for the provided request body. + +[[url-shortening-api-codes]] +==== Response code + +`200`:: + Indicates a successful call. + +[[url-shortening-api-example]] +==== Example + +[source,js] +-------------------------------------------------- +POST 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: + +[source,js] +-------------------------------------------------- +{ + "urlId": "f73b295ff92718b26bc94edac766d8e3" +} +-------------------------------------------------- + +For easy sharing, construct the shortened {kib} URL: + +`http://localhost:5601/goto/f73b295ff92718b26bc94edac766d8e3` diff --git a/docs/api/url_shortening/shorten_url.asciidoc b/docs/api/url_shortening/shorten_url.asciidoc deleted file mode 100644 index 0e04a32efe35e..0000000000000 --- a/docs/api/url_shortening/shorten_url.asciidoc +++ /dev/null @@ -1,55 +0,0 @@ -[[shorten-url-api]] -=== Shorten URL API -++++ -Shorten URL -++++ - -experimental[] Convert a {kib} URL into a token. - -[[url-shortening-api-request]] -==== Request - -`POST /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`. - -[[url-shortening-api-response-body]] -==== Response body - -urlId:: A top level property that contains the shortened URL token for the provided request body. - -[[url-shortening-api-codes]] -==== Response code - -`200`:: - Indicates a successful call. - -[[url-shortening-api-example]] -==== Example - -[source,js] --------------------------------------------------- -POST 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: - -[source,js] --------------------------------------------------- -{ - "urlId": "f73b295ff92718b26bc94edac766d8e3" -} --------------------------------------------------- - -For easy sharing, construct the shortened {kib} URL: - -`http://localhost:5601/goto/f73b295ff92718b26bc94edac766d8e3` - diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc new file mode 100644 index 0000000000000..82071af463636 --- /dev/null +++ b/docs/api/using-api.asciidoc @@ -0,0 +1,46 @@ +[[using-api]] +== Using the APIs + +Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols. + +It is recommended that you use HTTPs on port 5601 because it is more secure. + +NOTE: The {kib} Console supports only Elasticsearch APIs. You are unable to interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to <>. + +[float] +[[api-authentication]] +=== Authentication +{kib} supports token-based authentication with the same username and password that you use to log into the {kib} Console. + +[float] +[[api-calls]] +=== API calls +API calls are stateless. Each request that you make happens in isolation from other calls and must include all of the necessary information for {kib} to fulfill the request. API requests return JSON output, which is a format that is machine-readable and works well for automation. + +Calls to the API endpoints require different operations. To interact with the {kib} APIs, use the following operations: + +* *GET* - Fetches the information. + +* *POST* - Adds new information. + +* *PUT* - Updates the existing information. + +* *DELETE* - Removes the information. + +For example, the following `curl` command exports a dashboard: + +[source,sh] +-- +curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c" +-- + +The following {kib} APIs are available: + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> diff --git a/docs/dev-tools/console/console.asciidoc b/docs/dev-tools/console/console.asciidoc index a678e7189abec..26620688499af 100644 --- a/docs/dev-tools/console/console.asciidoc +++ b/docs/dev-tools/console/console.asciidoc @@ -12,6 +12,8 @@ To get started, go to *Dev Tools > Console*. [role="screenshot"] image::dev-tools/console/images/console.png["Console"] +NOTE: You are unable to interact with the REST API of {kib} with the Console. + [float] [[console-api]] === Write requests diff --git a/docs/user/api.asciidoc b/docs/user/api.asciidoc index 8ad8b71c789f4..20f1fc89367f2 100644 --- a/docs/user/api.asciidoc +++ b/docs/user/api.asciidoc @@ -8,7 +8,7 @@ integration with {kib}, or automating certain aspects of configuring and deploying {kib}. Each API is experimental and can include breaking changes in any version of -{kib}, or might have been entirely removed from {kib}. +{kib}, or might be entirely removed from {kib}. //// Each API has one of the following labels: @@ -29,25 +29,14 @@ entirely. If a label is missing from an API, it is considered `experimental`. //// -NOTE: You cannot access the APIs via the Console in {kib}. - -[float] -== APIs -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -- +include::{kib-repo-dir}/api/using-api.asciidoc[] include::{kib-repo-dir}/api/features.asciidoc[] include::{kib-repo-dir}/api/spaces-management.asciidoc[] include::{kib-repo-dir}/api/role-management.asciidoc[] include::{kib-repo-dir}/api/saved-objects.asciidoc[] -include::{kib-repo-dir}/api/dashboard-import.asciidoc[] +include::{kib-repo-dir}/api/dashboard-api.asciidoc[] include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[] include::{kib-repo-dir}/api/url-shortening.asciidoc[] include::{kib-repo-dir}/api/upgrade-assistant.asciidoc[]