Deprecate the 'local' parameter of /_cat/indices

docs/reference/cat/indices.asciidoc

@@ -75,6 +75,14 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=help]
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=include-unloaded-segments]
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local]
++
+--
+`local`::
+(Optional, boolean) If true, the request retrieves information from the local node
+only. Defaults to false, which means information is retrieved from the master node.
+deprecated::[8.0,This parameter does not cause this API to act locally. It will be
+removed in version 8.0.]
+--
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 

rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json

@@ -51,7 +51,11 @@
       },
       "local":{
         "type":"boolean",
-        "description":"Return local information, do not retrieve the state from master node (default: false)"
+        "description":"Return local information, do not retrieve the state from master node (default: false)",
+        "deprecated":{
+          "version":"8.0.0",
+          "description":"This parameter does not cause this API to act locally."
+        }
       },
       "master_timeout":{
         "type":"time",

server/src/main/java/org/elasticsearch/rest/action/cat/RestIndicesAction.java

@@ -39,6 +39,7 @@
 import org.elasticsearch.cluster.metadata.IndexMetadata;
 import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.Table;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.time.DateFormatter;
 import org.elasticsearch.common.unit.TimeValue;
@@ -66,6 +67,9 @@
 import static org.elasticsearch.rest.RestRequest.Method.GET;
 
 public class RestIndicesAction extends AbstractCatAction {
+    private static final DeprecationLogger DEPRECATION_LOGGER = DeprecationLogger.getLogger(RestIndicesAction.class);
+    static final String LOCAL_DEPRECATED_MESSAGE = "Deprecated parameter [local] used. This parameter does not cause this API to act " +
+        "locally, and should not be used. It will be unsupported in version 8.0.";
 
     private static final DateFormatter STRICT_DATE_TIME_FORMATTER = DateFormatter.forPattern("strict_date_time");
 
@@ -91,6 +95,9 @@ protected void documentation(StringBuilder sb) {
     public RestChannelConsumer doCatRequest(final RestRequest request, final NodeClient client) {
         final String[] indices = Strings.splitStringByCommaToArray(request.param("index"));
         final IndicesOptions indicesOptions = IndicesOptions.fromRequest(request, IndicesOptions.strictExpand());
+        if (request.hasParam("local")) {
+            DEPRECATION_LOGGER.deprecate("local", LOCAL_DEPRECATED_MESSAGE);
+        }
         final boolean local = request.paramAsBoolean("local", false);
         final TimeValue masterNodeTimeout = request.paramAsTime("master_timeout", DEFAULT_MASTER_NODE_TIMEOUT);
         final boolean includeUnloadedSegments = request.paramAsBoolean("include_unloaded_segments", false);

server/src/test/java/org/elasticsearch/rest/action/cat/RestIndicesActionTests.java

@@ -22,6 +22,7 @@
 import org.elasticsearch.Version;
 import org.elasticsearch.action.admin.indices.stats.CommonStats;
 import org.elasticsearch.action.admin.indices.stats.IndexStats;
+import org.elasticsearch.client.node.NodeClient;
 import org.elasticsearch.cluster.health.ClusterHealthStatus;
 import org.elasticsearch.cluster.health.ClusterIndexHealth;
 import org.elasticsearch.cluster.metadata.IndexMetadata;
@@ -36,6 +37,8 @@
 import org.elasticsearch.index.shard.ShardId;
 import org.elasticsearch.test.ESTestCase;
 import org.elasticsearch.test.rest.FakeRestRequest;
+import org.elasticsearch.threadpool.TestThreadPool;
+import org.junit.Before;
 
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -50,6 +53,13 @@
 
 public class RestIndicesActionTests extends ESTestCase {
 
+    private RestIndicesAction action;
+
+    @Before
+    public void setUpAction() {
+        action = new RestIndicesAction();
+    }
+
     public void testBuildTable() {
         final int numIndices = randomIntBetween(3, 20);
         final Map<String, Settings> indicesSettings = new LinkedHashMap<>();
@@ -166,4 +176,16 @@ public void testBuildTable() {
             }
         }
     }
+
+    public void testCatIndicesWithLocalDeprecationWarning() {
+        TestThreadPool threadPool = new TestThreadPool(RestIndicesActionTests.class.getName());
+        NodeClient client = new NodeClient(Settings.EMPTY, threadPool);
+        FakeRestRequest request = new FakeRestRequest();
+        request.params().put("local", randomFrom("", "true", "false"));
+
+        action.doCatRequest(request, client);
+        assertWarnings(RestIndicesAction.LOCAL_DEPRECATED_MESSAGE);
+
+        terminate(threadPool);
+    }
 }