[DOCS] Format X-Pack migration APIs (elastic/x-pack-elasticsearch#2378)

Original commit: elastic/x-pack-elasticsearch@502d77b975

docs/en/rest-api/migration/assistance.asciidoc

@@ -2,11 +2,35 @@
 [[migration-api-assistance]]
 === Migration Assistance API
 
-The Migration Assistance API analyzes existing indices in the cluster and returns the information
+The Migration Assistance API analyzes existing indices in the cluster and
-about indices that require some changes before the cluster can be upgraded to the next major version.
+returns the information about indices that require some changes before the
+cluster can be upgraded to the next major version.
 
-To see a list of indices that needs to be upgraded or reindexed, submit a GET request to the
+[float]
-`/_xpack/migration/assistance` endpoint:
+==== Request
+
+`GET /_xpack/migration/assistance` +
+
+`GET /_xpack/migration/assistance/<index_name>`
+
+//==== Description
+
+[float]
+==== Path Parameters
+
+`index_name`::
+  (string) Identifier for the index. It can be an index name or a wildcard
+  expression.
+
+//==== Query Parameters
+
+//==== Authorization
+
+[float]
+==== Examples
+
+To see a list of indices that needs to be upgraded or reindexed, submit a GET
+request to the `/_xpack/migration/assistance` endpoint:
 
 [source,js]
 --------------------------------------------------
@@ -38,8 +62,8 @@ A successful call returns a list of indices that need to updated or reindexed:
 --------------------------------------------------
 // NOTCONSOLE
 
-To check a particular index or set of indices, specify this index name or mask as the last part of the
+To check a particular index or set of indices, specify this index name or mask
-`/_xpack/migration/assistance/index_name` endpoint:
+as the last part of the `/_xpack/migration/assistance/index_name` endpoint:
 
 [source,js]
 --------------------------------------------------
@@ -48,8 +72,8 @@ GET /_xpack/migration/assistance/my_*
 // CONSOLE
 // TEST[skip:cannot create an old index in docs test]
 
-A successful call returns a list of indices that needs to updated or reindexed and match the index specified
+A successful call returns a list of indices that needs to updated or reindexed
-on the endpoint:
+and match the index specified on the endpoint:
 
 [source,js]
 --------------------------------------------------
@@ -64,4 +88,4 @@ on the endpoint:
   }
 }
 --------------------------------------------------
-// NOTCONSOLE
+// NOTCONSOLE

docs/en/rest-api/migration/deprecation.asciidoc

@@ -2,10 +2,36 @@
 [[migration-api-deprecation]]
 == Deprecation Info APIs
 
-The deprecation API is to be used to retrieve information about different cluster, node, and index level
+The deprecation API is to be used to retrieve information about different
-settings that use deprecated features that will be removed or changed in the next major version.
+cluster, node, and index level settings that use deprecated features that will
+be removed or changed in the next major version.
 
-To see the list of offenders in your cluster, submit a GET request to the `_xpack/migration/deprecations` endpoint:
+[float]
+=== Request
+
+`GET /_xpack/migration/deprecations` +
+
+`GET /<index_name>/_xpack/migration/deprecations`
+
+//=== Description
+
+[float]
+=== Path Parameters
+
+`index_name`::
+  (string) Identifier for the index. It can be an index name or a wildcard
+  expression. When you specify this parameter, only index-level deprecations for
+  the specified indices are returned.
+
+//=== Query Parameters
+
+//=== Authorization
+
+[float]
+=== Examples
+
+To see the list of offenders in your cluster, submit a GET request to the
+`_xpack/migration/deprecations` endpoint:
 
 [source,js]
 --------------------------------------------------
@@ -43,8 +69,9 @@ Example response:
 --------------------------------------------------
 // NOTCONSOLE
 
-The response you will receive will break down all the specific forward-incompatible settings that your
+The response breaks down all the specific forward-incompatible settings that you
-cluster should resolve before upgrading. Any offending setting will be represented as a deprecation warning.
+should resolve before upgrading your cluster. Any offending settings are
+represented as a deprecation warning.
 
 The following is an example deprecation warning:
 
@@ -59,25 +86,31 @@ The following is an example deprecation warning:
 --------------------------------------------------
 // NOTCONSOLE
 
-As is shown, there is a `level` property that describes how significant the issue may be.
+As is shown, there is a `level` property that describes the significance of the
+issue.
 
 |=======
-|none | everything is good
+|none | Everything is good.
-|info | An advisory note that something has changed. No action needed
+|info | An advisory note that something has changed. No action needed.
-|warning | You can upgrade directly, but you are using deprecated functionality which will not be available in the next major version
+|warning | You can upgrade directly, but you are using deprecated functionality
-|critical | You cannot upgrade without fixing this problem
+which will not be available in the next major version.
+|critical | You cannot upgrade without fixing this problem.
 |=======
 
-`message` and the optional `details` provide descriptive information about the deprecation warning, while the `url`
+The `message` property and the optional `details` property provide descriptive
-property provides a link to the Breaking Changes Documentation, where more information about this change can be found.
+information about the deprecation warning. The `url` property provides a link to
+the Breaking Changes Documentation, where you can find more information about
+this change.
 
-Any cluster-level deprecation warnings can be found under
+Any cluster-level deprecation warnings can be found under the `cluster_settings`
-the `cluster_settings` key. Similarly, any node-level warnings will be found under `node_settings`. 
+key. Similarly, any node-level warnings are found under `node_settings`. Since
-Since only a select subset of your nodes may incorporate these settings, it is important to read the
+only a select subset of your nodes might incorporate these settings, it is
-`details` section for more information about which nodes are to be updated. Index warnings are
+important to read the `details` section for more information about which nodes
-sectioned off per index and can be filtered using an index-pattern in the query.
+are affected. Index warnings are sectioned off per index and can be filtered
+using an index-pattern in the query.
 
-Example request that only shows index-level deprecations of all `logstash-*` indices:
+The following example request shows only index-level deprecations of all
+`logstash-*` indices:
 
 [source,js]
 --------------------------------------------------

docs/en/rest-api/migration/upgrade.asciidoc

@@ -2,10 +2,39 @@
 [[migration-api-upgrade]]
 === Migration Upgrade API
 
-The Migration Upgrade API performs the upgrade of internal indices to make them compatible with the next major version.
+The Migration Upgrade API performs the upgrade of internal indices to make them
+compatible with the next major version.
 
-Indices need to be upgraded one at a time by submitting a POST request to the
+[float]
-`/_xpack/migration/upgrade/index_name` endpoint:
+==== Request
+
+`POST /_xpack/migration/upgrade/<index_name>`
+
+[float]
+==== Description
+
+Indices must be upgraded one at a time.
+
+[float]
+==== Path Parameters
+
+`index_name`::
+  (string) Identifier for the index.
+
+`wait_for_completion`::
+  (boolean) Defines whether the upgrade call blocks until the upgrade process is
+  finished. The default value is `true`. If set to `false`, the upgrade can be
+  performed asynchronously.
+
+//==== Query Parameters
+
+//==== Authorization
+
+[float]
+==== Examples
+
+The following example submits a POST request to the
+`/_xpack/migration/upgrade/<index_name>` endpoint:
 
 [source,js]
 --------------------------------------------------
@@ -38,8 +67,8 @@ A successful call returns the statistics about the upgrade process:
 --------------------------------------------------
 // NOTCONSOLE
 
-By default, the upgrade call blocks until the upgrade process is finished. For large indices the upgrade can be
+The following example upgrades a large index asynchronously by specifying the
-performed asynchronously by specifying `wait_for_completion=false` parameter:
+`wait_for_completion` parameter:
 
 [source,js]
 --------------------------------------------------
@@ -58,7 +87,8 @@ This call should return the id of the upgrade process task:
 --------------------------------------------------
 // NOTCONSOLE
 
-The status of the running or finished upgrade requests can be obtained using <<tasks,Task API>>:
+The status of the running or finished upgrade requests can be obtained by using
+the <<tasks,Task API>>:
 
 [source,js]
 --------------------------------------------------
@@ -102,7 +132,7 @@ GET _tasks/PFvgv7T6TGumRyFF3vqTFg:1137?detailed=true
 --------------------------------------------------
 // NOTCONSOLE
 
-<1> `true` in the `completed` field indicates that the upgrade request has finished, `false` means that
+<1> If the `completed` field value is `true`, the upgrade request has finished.
-request is still executing
+If it is `false`, the request is still running.
 
-<2> the `response` field contains the status of the upgrade request
+<2> The `response` field contains the status of the upgrade request.