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

* [DOCS] Updates API requests and examples * Review comments
elastic · Mar 20, 2020 · fda3196 · fda3196
1 parent cf9b64e
commit fda3196
Show file tree

Hide file tree

Showing 37 changed files with 308 additions and 619 deletions.
diff --git a/docs/api/dashboard/export-dashboard.asciidoc b/docs/api/dashboard/export-dashboard.asciidoc
@@ -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`.
diff --git a/docs/api/dashboard/import-dashboard.asciidoc b/docs/api/dashboard/import-dashboard.asciidoc
@@ -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": [
     {

diff --git a/docs/api/features.asciidoc b/docs/api/features.asciidoc
@@ -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",

diff --git a/docs/api/logstash-configuration-management.asciidoc b/docs/api/logstash-configuration-management.asciidoc
@@ -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[]
-
-
diff --git a/docs/api/logstash-configuration-management/create-logstash.asciidoc b/docs/api/logstash-configuration-management/create-logstash.asciidoc
@@ -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": {

diff --git a/docs/api/logstash-configuration-management/delete-pipeline.asciidoc b/docs/api/logstash-configuration-management/delete-pipeline.asciidoc
@@ -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
-
diff --git a/docs/api/logstash-configuration-management/list-pipeline.asciidoc b/docs/api/logstash-configuration-management/list-pipeline.asciidoc
@@ -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.
diff --git a/docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc b/docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc
@@ -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"
   }
 }
---------------------------------------------------
+--------------------------------------------------
diff --git a/docs/api/role-management.asciidoc b/docs/api/role-management.asciidoc
@@ -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:
 

diff --git a/docs/api/role-management/delete.asciidoc b/docs/api/role-management/delete.asciidoc
@@ -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.
diff --git a/docs/api/role-management/get-all.asciidoc b/docs/api/role-management/get-all.asciidoc
@@ -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": [ ]
   }
 ]
---------------------------------------------------
+--------------------------------------------------
diff --git a/docs/api/role-management/get.asciidoc b/docs/api/role-management/get.asciidoc
@@ -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",