[DOCS] Separate add index alias API docs (#46086)

docs/reference/indices.asciidoc

@@ -34,6 +34,7 @@ index settings, aliases, mappings, and index templates.
 [float]
 [[alias-management]]
 === Alias management:
+* <<indices-add-alias>>
 * <<indices-get-alias>>
 * <<indices-alias-exists>>
 * <<indices-aliases>>
@@ -94,6 +95,8 @@ include::indices/get-field-mapping.asciidoc[]
 
 include::indices/types-exists.asciidoc[]
 
+include::indices/add-alias.asciidoc[]
+
 include::indices/get-alias.asciidoc[]
 
 include::indices/alias-exists.asciidoc[]

docs/reference/indices/add-alias.asciidoc

@@ -0,0 +1,139 @@
+[[indices-add-alias]]
+=== Add index alias API
+++++
+<titleabbrev>Add index alias</titleabbrev>
+++++
+
+Creates or updates an index alias.
+
+include::alias-exists.asciidoc[tag=index-alias-def]
+
+[source,js]
+----
+PUT /twitter/_alias/alias1
+----
+// CONSOLE
+// TEST[setup:twitter]
+
+
+[[add-alias-api-request]]
+==== {api-request-title}
+
+`PUT /<index>/_alias/<alias>`
+
+`POST /<index>/_alias/<alias>`
+
+`PUT /<index>/_aliases/<alias>`
+
+`POST /<index>/_aliases/<alias>`
+
+
+[[add-alias-api-path-params]]
+==== {api-path-parms-title}
+
+`<index>`::
+(Required, string)
+Comma-separated list or wildcard expression of index names
+to add to the alias.
++
+To add all indices in the cluster to the alias,
+use a value of `_all`.
+
+`<alias>`::
+(Required, string)
+Name of the index alias to create or update.
+
+
+[[add-alias-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+
+[[add-alias-api-request-body]]
+==== {api-request-body-title}
+
+`filter`::
+(Required, query object)
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias-filter]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-routing]
+
+[[add-alias-api-example]]
+==== {api-examples-title}
+
+[[alias-adding]]
+===== Add a time-based alias
+
+The following request creates an alias, `2030`,
+for the `logs_20302801` index.
+
+[source,js]
+--------------------------------------------------
+PUT /logs_20302801/_alias/2030
+--------------------------------------------------
+// CONSOLE
+// TEST[s/^/PUT logs_20302801\n/]
+
+[[add-alias-api-user-ex]]
+===== Add a user-based alias
+
+First, create an index, `users`,
+with a mapping for the `user_id` field:
+
+[source,js]
+--------------------------------------------------
+PUT /users
+{
+    "mappings" : {
+        "properties" : {
+            "user_id" : {"type" : "integer"}
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+
+Then add the index alias for a specific user, `user_12`:
+
+[source,js]
+--------------------------------------------------
+PUT /users/_alias/user_12
+{
+    "routing" : "12",
+    "filter" : {
+        "term" : {
+            "user_id" : 12
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+[[alias-index-creation]]
+===== Add an alias during index creation
+
+You can use the <<create-index-aliases,create index API>>
+to add an index alias during index creation.
+
+[source,js]
+--------------------------------------------------
+PUT /logs_20302801
+{
+    "mappings" : {
+        "properties" : {
+            "year" : {"type" : "integer"}
+        }
+    },
+    "aliases" : {
+        "current_day" : {},
+        "2030" : {
+            "filter" : {
+                "term" : {"year" : 2030 }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE

docs/reference/indices/aliases.asciidoc

@@ -339,122 +339,3 @@ only reference one index, will have that referenced index behave as if it is the
 until an additional index is referenced. At that point, there will be no write index and
 writes will be rejected.
 =====================================
-
-[float]
-[[alias-adding]]
-==== Add a single alias
-
-An alias can also be added with the endpoint
-
-`PUT /{index}/_alias/{name}`
-
-
-where
-
-[horizontal]
-`index`::   The index the alias refers to. Can be any of `* | _all | glob pattern | name1, name2, …`
-`name`::   The name of the alias. This is a required option.
-`routing`:: An optional routing that can be associated with an alias.
-`filter`::  An optional filter that can be associated with an alias.
-
-You can also use the plural `_aliases`.
-
-[float]
-===== Examples:
-
-Adding time based alias::
-+
---
-[source,js]
---------------------------------------------------
-PUT /logs_201305/_alias/2013
---------------------------------------------------
-// CONSOLE
-// TEST[s/^/PUT logs_201305\n/]
---
-
-Adding a user alias::
-+
---
-First create the index and add a mapping for the `user_id` field:
-
-[source,js]
---------------------------------------------------
-PUT /users
-{
-    "mappings" : {
-        "properties" : {
-            "user_id" : {"type" : "integer"}
-        }
-    }
-}
---------------------------------------------------
-// CONSOLE
-
-Then add the alias for a specific user:
-
-[source,js]
---------------------------------------------------
-PUT /users/_alias/user_12
-{
-    "routing" : "12",
-    "filter" : {
-        "term" : {
-            "user_id" : 12
-        }
-    }
-}
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
---
-
-[float]
-[[alias-index-creation]]
-==== Aliases during index creation
-
-Aliases can also be specified during <<create-index-aliases,index creation>>:
-
-[source,js]
---------------------------------------------------
-PUT /logs_20162801
-{
-    "mappings" : {
-        "properties" : {
-            "year" : {"type" : "integer"}
-        }
-    },
-    "aliases" : {
-        "current_day" : {},
-        "2016" : {
-            "filter" : {
-                "term" : {"year" : 2016 }
-            }
-        }
-    }
-}
---------------------------------------------------
-// CONSOLE
-
-[float]
-[[deleting]]
-==== Delete aliases
-
-
-The rest endpoint is: `/{index}/_alias/{name}`
-
-where
-
-[horizontal]
-`index`::  `* | _all | glob pattern | name1, name2, …`
-`name`::  `* | _all | glob pattern | name1, name2, …`
-
-Alternatively you can use the plural `_aliases`. Example:
-
-[source,js]
---------------------------------------------------
-DELETE /logs_20162801/_alias/current_day
---------------------------------------------------
-// CONSOLE
-// TEST[continued]

docs/reference/rest-api/common-parms.asciidoc

@@ -38,22 +38,19 @@ Wildcard expressions are not accepted.
 --
 end::expand-wildcards[]
 
-tag::cat-h[]
-`h`::
-(Optional, string) Comma-separated list of column names to display.
-end::cat-h[]
-
 tag::flat-settings[]
 `flat_settings`::
 (Optional, boolean) If `true`, returns settings in flat format. Defaults to
 `false`.
 end::flat-settings[]
 
-tag::help[]
-`help`::
-(Optional, boolean) If `true`, the response returns help information. Defaults
-to `false`.
-end::help[]
+tag::index-alias-filter[]
+<<query-dsl-bool-query, Filter query>>
+used to limit the index alias.
++
+If specified,
+the index alias only applies to documents returned by the filter.
+end::index-alias-filter[]
 
 tag::http-format[]
 `format`::
@@ -62,6 +59,17 @@ https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html[HTTP accept header].
 Valid values include JSON, YAML, etc.
 end::http-format[]
 
+tag::cat-h[]
+`h`::
+(Optional, string) Comma-separated list of column names to display.
+end::cat-h[]
+
+tag::help[]
+`help`::
+(Optional, boolean) If `true`, the response returns help information. Defaults
+to `false`.
+end::help[]
+
 tag::include-defaults[]
 `include_defaults`::
 (Optional, string) If `true`, return all default settings in the response.
@@ -153,6 +161,13 @@ tag::doc-routing[]
 (Optional, string) Target the specified primary shard.
 end::doc-routing[]
 
+tag::index-routing[]
+`routing`::
+(Optional, string)
+Custom <<mapping-routing-field, routing value>>
+used to route operations to a specific shard.
+end::index-routing[]
+
 tag::doc-version[]
 `version`::
 (Optional, integer) Explicit version number for concurrency control.