[DOCS] Fixes to API docs (elastic#71678) (elastic#71766)

* [DOCS] Fixes to API docs * Fixes rogue -u # Conflicts: # docs/api/saved-objects/create.asciidoc # docs/api/saved-objects/export.asciidoc # docs/api/upgrade-assistant/batch_reindexing.asciidoc Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
KOTungseth · Jul 14, 2020 · b5b6953 · b5b6953
1 parent d632577
commit b5b6953
Show file tree

Hide file tree

Showing 23 changed files with 130 additions and 41 deletions.
diff --git a/docs/api/dashboard/export-dashboard.asciidoc b/docs/api/dashboard/export-dashboard.asciidoc
@@ -35,7 +35,7 @@ experimental[] Export dashboards and corresponding saved objects.
 
 [source,sh]
 --------------------------------------------------
-$ curl -X GET "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c" <1>
+$ curl -X GET api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c <1>
 --------------------------------------------------
 // KIBANA
 

diff --git a/docs/api/dashboard/import-dashboard.asciidoc b/docs/api/dashboard/import-dashboard.asciidoc
@@ -42,7 +42,7 @@ Use the complete response body from the <<dashboard-api-export, Export dashboard
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/kibana/dashboards/import?exclude=index-pattern"
+$ curl -X POST api/kibana/dashboards/import?exclude=index-pattern
 {
   "objects": [
     {

diff --git a/docs/api/logstash-configuration-management/create-logstash.asciidoc b/docs/api/logstash-configuration-management/create-logstash.asciidoc
@@ -41,7 +41,7 @@ experimental[] Create a centrally-managed Logstash pipeline, or update an existi
 
 [source,sh]
 --------------------------------------------------
-$ curl -X PUT "localhost:5601/api/logstash/pipeline/hello-world"
+$ curl -X PUT 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
@@ -28,6 +28,6 @@ experimental[] Delete a centrally-managed Logstash pipeline.
 
 [source,sh]
 --------------------------------------------------
-$ curl -X DELETE "localhost:5601/api/logstash/pipeline/hello-world"
+$ curl -X DELETE api/logstash/pipeline/hello-world
 --------------------------------------------------
 // KIBANA
diff --git a/docs/api/role-management/put.asciidoc b/docs/api/role-management/put.asciidoc
@@ -58,7 +58,7 @@ Grant access to various features in all spaces:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
+$ curl -X PUT api/security/role/my_kibana_role
 {
   "metadata" : {
     "version" : 1
@@ -127,7 +127,7 @@ Grant dashboard-only access to only the Marketing space:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
+$ curl -X PUT api/security/role/my_kibana_role
 {
   "metadata" : {
     "version" : 1
@@ -155,7 +155,7 @@ Grant full access to all features in the Default space:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
+$ curl -X PUT api/security/role/my_kibana_role
 {
   "metadata" : {
     "version" : 1
@@ -182,7 +182,7 @@ Grant different access to different spaces:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
+$ curl -X PUT api/security/role/my_kibana_role
 {
   "metadata" : {
     "version" : 1
@@ -218,7 +218,7 @@ Grant access to {kib} and {es}:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role"
+$ curl -X PUT api/security/role/my_kibana_role
 {
   "metadata" : {
     "version" : 1

diff --git a/docs/api/saved-objects/bulk_create.asciidoc b/docs/api/saved-objects/bulk_create.asciidoc
@@ -65,7 +65,7 @@ Create an index pattern with the `my-pattern` ID, and a dashboard with the `my-d
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/_bulk_create"
+$ curl -X POST api/saved_objects/_bulk_create
 [
   {
     "type": "index-pattern",

diff --git a/docs/api/saved-objects/bulk_get.asciidoc b/docs/api/saved-objects/bulk_get.asciidoc
@@ -52,7 +52,7 @@ Retrieve an index pattern with the `my-pattern` ID, and a dashboard with the `my
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/_bulk_get"
+$ curl -X POST api/saved_objects/_bulk_get
 [
   {
     "type": "index-pattern",

diff --git a/docs/api/saved-objects/create.asciidoc b/docs/api/saved-objects/create.asciidoc
@@ -57,7 +57,7 @@ any data that you send to the API is properly formed.
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/index-pattern/my-pattern"
+$ curl -X POST api/saved_objects/index-pattern/my-pattern  -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
 {
   "attributes": {
     "title": "my-pattern-*"

diff --git a/docs/api/saved-objects/delete.asciidoc b/docs/api/saved-objects/delete.asciidoc
@@ -39,6 +39,6 @@ Delete an index pattern object with the `my-pattern` ID:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X DELETE "localhost:5601/api/saved_objects/index-pattern/my-pattern"
+$ curl -X DELETE api/saved_objects/index-pattern/my-pattern
 --------------------------------------------------
 // KIBANA
diff --git a/docs/api/saved-objects/export.asciidoc b/docs/api/saved-objects/export.asciidoc
@@ -68,7 +68,7 @@ Export all index pattern saved objects:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/_export"
+$ curl -X POST api/saved_objects/_export -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
 {
   "type": "index-pattern"
 }
@@ -79,7 +79,7 @@ Export all index pattern saved objects and exclude the export summary from the s
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/_export"
+$ curl -X POST api/saved_objects/_export -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
 {
   "type": "index-pattern",
   "excludeExportDetails": true
@@ -91,7 +91,7 @@ Export a specific saved object:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/_export"
+$ curl -X POST api/saved_objects/_export -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
 {
   "objects": [
     {
@@ -107,7 +107,7 @@ Export a specific saved object and it's related objects :
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/_export"
+$ curl -X POST api/saved_objects/_export -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
 {
   "objects": [
     {

diff --git a/docs/api/saved-objects/find.asciidoc b/docs/api/saved-objects/find.asciidoc
@@ -69,7 +69,7 @@ Find index patterns with titles that start with `my`:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X GET "localhost:5601/api/saved_objects/_find?type=index-pattern&search_fields=title&search=my*"
+$ curl -X GET api/saved_objects/_find?type=index-pattern&search_fields=title&search=my*
 --------------------------------------------------
 // KIBANA
 
@@ -97,6 +97,6 @@ query parameter for each value:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X GET "localhost:5601/api/saved_objects/_find?fields=id&fields=title"
+$ curl -X GET api/saved_objects/_find?fields=id&fields=title
 --------------------------------------------------
 // KIBANA
diff --git a/docs/api/saved-objects/get.asciidoc b/docs/api/saved-objects/get.asciidoc
@@ -39,7 +39,7 @@ Retrieve the index pattern object with the `my-pattern` ID:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X GET "localhost:5601/api/saved_objects/index-pattern/my-pattern"
+$ curl -X GET api/saved_objects/index-pattern/my-pattern
 --------------------------------------------------
 // KIBANA
 
@@ -61,7 +61,7 @@ Retrieve a dashboard object in the `testspace` by ID:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X GET "localhost:5601/s/testspace/api/saved_objects/dashboard/7adfa750-4c81-11e8-b3d7-01146121b73d"
+$ curl -X GET s/testspace/api/saved_objects/dashboard/7adfa750-4c81-11e8-b3d7-01146121b73d
 --------------------------------------------------
 // KIBANA
 

diff --git a/docs/api/saved-objects/import.asciidoc b/docs/api/saved-objects/import.asciidoc
@@ -57,7 +57,7 @@ Import an index pattern and dashboard:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson
+$ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson
 --------------------------------------------------
 // KIBANA
 
@@ -83,7 +83,7 @@ Import an index pattern and dashboard that includes a conflict on the index patt
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson
+$ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson
 --------------------------------------------------
 // KIBANA
 
@@ -119,7 +119,7 @@ Import a visualization and dashboard with an index pattern for the visualization
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson
+$ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson
 --------------------------------------------------
 // KIBANA
 

diff --git a/docs/api/saved-objects/resolve_import_errors.asciidoc b/docs/api/saved-objects/resolve_import_errors.asciidoc
@@ -63,7 +63,7 @@ Retry a dashboard import:
 
 [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"}]'
+$ curl -X POST api/saved_objects/_resolve_import_errors -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"dashboard","id":"my-dashboard"}]'
 --------------------------------------------------
 // KIBANA
 
@@ -88,7 +88,7 @@ Resolve errors for a dashboard and overwrite the existing saved object:
 
 [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}]'
+$ curl -X POST api/saved_objects/_resolve_import_errors -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"dashboard","id":"my-dashboard","overwrite":true}]'
 --------------------------------------------------
 // KIBANA
 
@@ -114,7 +114,7 @@ Resolve errors for a visualization by replacing the index pattern with another:
 
 [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"}]}]'
+$ curl -X POST 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
 

diff --git a/docs/api/saved-objects/update.asciidoc b/docs/api/saved-objects/update.asciidoc
@@ -49,7 +49,7 @@ Update an existing index pattern object,`my-pattern`, with a different title:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X PUT "localhost:5601/api/saved_objects/index-pattern/my-pattern"
+$ curl -X PUT api/saved_objects/index-pattern/my-pattern
 {
   "attributes": {
     "title": "some-other-pattern-*"

diff --git a/docs/api/spaces-management/copy_saved_objects.asciidoc b/docs/api/spaces-management/copy_saved_objects.asciidoc
@@ -73,7 +73,7 @@ Copy a dashboard with the `my-dashboard` ID, including all references from the `
 
 [source,sh]
 ----
-$ curl -X POST "localhost:5601/api/spaces/_copy_saved_objects"
+$ curl -X POST api/spaces/_copy_saved_objects
 {
   "objects": [{
     "type": "dashboard",
@@ -114,7 +114,7 @@ Copy a visualization with the `my-viz` ID from the `marketing` space to the `def
 
 [source,sh]
 ----
-$ curl -X POST "localhost:5601/s/marketing/api/spaces/_copy_saved_objects"
+$ curl -X POST s/marketing/api/spaces/_copy_saved_objects
 {
   "objects": [{
     "type": "visualization",

diff --git a/docs/api/spaces-management/post.asciidoc b/docs/api/spaces-management/post.asciidoc
@@ -47,7 +47,7 @@ experimental[] Create a {kib} space.
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST "localhost:5601/api/spaces/space"
+$ curl -X POST api/spaces/space
 {
   "id": "marketing",
   "name": "Marketing",

diff --git a/docs/api/spaces-management/put.asciidoc b/docs/api/spaces-management/put.asciidoc
@@ -47,7 +47,7 @@ experimental[] Update an existing {kib} space.
 
 [source,sh]
 --------------------------------------------------
-$ curl -X PUT "localhost:5601/api/spaces/space/marketing"
+$ curl -X PUT api/spaces/space/marketing
 {
   "id": "marketing",
   "name": "Marketing",

diff --git a/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc b/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc
@@ -78,7 +78,7 @@ Overwrite an index pattern in the `marketing` space, and a visualization in the
 
 [source,sh]
 ----
-$ curl -X POST "localhost:5601/api/spaces/_resolve_copy_saved_objects_errors"
+$ curl -X POST api/spaces/_resolve_copy_saved_objects_errors
 {
   "objects": [{
     "type": "dashboard",

diff --git a/docs/api/upgrade-assistant/batch_reindexing.asciidoc b/docs/api/upgrade-assistant/batch_reindexing.asciidoc
@@ -0,0 +1,83 @@
+[[batch-start-resume-reindex]]
+=== Batch start or resume reindex API
+++++
+<titleabbrev>Batch start or resume reindex</titleabbrev>
+++++
+
+experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."]
+
+Start or resume multiple reindexing tasks in one request. Additionally, reindexing tasks started or resumed
+via the batch endpoint will be placed on a queue and executed one-by-one, which ensures that minimal cluster resources
+are consumed over time.
+
+[[batch-start-resume-reindex-request]]
+==== Request
+
+`POST /api/upgrade_assistant/reindex/batch`
+
+[[batch-start-resume-reindex-request-body]]
+==== Request body
+
+`indexNames`::
+  (Required, array) The list of index names to be reindexed.
+
+[[batch-start-resume-reindex-codes]]
+==== Response code
+
+`200`::
+  Indicates a successful call.
+
+[[batch-start-resume-example]]
+==== Example
+
+[source,js]
+--------------------------------------------------
+$ curl -X POST api/upgrade_assistant/reindex/batch
+{
+  "indexNames": [ <1>
+    "index1",
+    "index2"
+  ]
+}
+--------------------------------------------------
+// KIBANA
+
+<1> The order of the indices determines the order that the reindex tasks are executed.
+
+Similar to the <<start-resume-reindex, start or resume endpoint>>, the API returns the following:
+
+[source,js]
+--------------------------------------------------
+{
+  "enqueued": [ <1>
+    {
+      "indexName": "index1",
+      "newIndexName": "reindexed-v8-index1",
+      "status": 3,
+      "lastCompletedStep": 0,
+      "locked": null,
+      "reindexTaskId": null,
+      "reindexTaskPercComplete": null,
+      "errorMessage": null,
+      "runningReindexCount": null,
+      "reindexOptions": { <2>
+        "queueSettings": {
+          "queuedAt": 1583406985489 <3>
+        }
+      }
+    }
+  ],
+  "errors": [ <4>
+    {
+      "indexName": "index2",
+      "message": "Something went wrong!"
+    }
+  ]
+}
+--------------------------------------------------
+
+<1> A list of reindex operations created, the order in the array indicates the order in which tasks will be executed.
+<2> Presence of this key indicates that the reindex job will occur in the batch.
+<3> A Unix timestamp of when the reindex task was placed in the queue.
+<4> A list of errors that may have occurred preventing the reindex task from being created.
+
diff --git a/docs/api/upgrade-assistant/check_reindex_status.asciidoc b/docs/api/upgrade-assistant/check_reindex_status.asciidoc
@@ -62,6 +62,7 @@ The API returns the following:
 
 `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.
-Original file line number
+Diff line change
@@ Expand Up / @@ -62,6 +62,7 @@ The API returns the following: @@
     `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.
@@ Expand Down @@