Deprecate the 'local' parameter of /_cat/indices (#62198)

Author: boicehuang

docs/reference/cat/indices.asciidoc

@@ -74,7 +74,10 @@ 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)
++
+deprecated::[7.10.0,"This parameter does not affect the request. It will be removed in a future release."]
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 
@@ -112,4 +115,4 @@ yellow open   my-index-000001  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200
 green  open   my-index-000002  nYFWZEO7TUiOjLQXBaYJpA   1   0          0            0       260b           260b
 --------------------------------------------------
 // TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
-// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]
+// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]

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 affect the request. It will be removed in a future release."
+        }
       },
       "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,8 @@
 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 = "The parameter [local] is deprecated and will be removed in a future release.";
 
     private static final DateFormatter STRICT_DATE_TIME_FORMATTER = DateFormatter.forPattern("strict_date_time");
 
@@ -96,6 +99,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);
+    }
 }