Deprecate local parameter for get field mapping request (#55014)

The usage of local parameter for GetFieldMappingRequest has been removed from the underlying transport action since v2.0.

This PR deprecates the parameter from rest layer. It will be removed in next major version.

client/rest-high-level/src/main/java/org/elasticsearch/client/IndicesRequestConverters.java

@@ -170,7 +170,6 @@ final class IndicesRequestConverters {
         RequestConverters.Params parameters = new RequestConverters.Params();
         parameters.withIndicesOptions(getFieldMappingsRequest.indicesOptions());
         parameters.withIncludeDefaults(getFieldMappingsRequest.includeDefaults());
-        parameters.withLocal(getFieldMappingsRequest.local());
         request.addParameters(parameters.asMap());
         return request;
     }

client/rest-high-level/src/main/java/org/elasticsearch/client/indices/GetFieldMappingsRequest.java

@@ -26,6 +26,7 @@ import org.elasticsearch.common.Strings;
 /** Request the mappings of specific fields */
 public class GetFieldMappingsRequest implements Validatable {
 
+    @Deprecated
     private boolean local = false;
 
     private String[] fields = Strings.EMPTY_ARRAY;
@@ -40,11 +41,13 @@ public class GetFieldMappingsRequest implements Validatable {
      * Indicate whether the receiving node should operate based on local index information or forward requests,
      * where needed, to other nodes. If running locally, request will not raise errors if running locally & missing indices.
      */
+    @Deprecated
     public GetFieldMappingsRequest local(boolean local) {
         this.local = local;
         return this;
     }
 
+    @Deprecated
     public boolean local() {
         return local;
     }

client/rest-high-level/src/test/java/org/elasticsearch/client/IndicesRequestConvertersTests.java

@@ -237,7 +237,6 @@ public class IndicesRequestConvertersTests extends ESTestCase {
         Map<String, String> expectedParams = new HashMap<>();
         RequestConvertersTests.setRandomIndicesOptions(getFieldMappingsRequest::indicesOptions, getFieldMappingsRequest::indicesOptions,
             expectedParams);
-        RequestConvertersTests.setRandomLocal(getFieldMappingsRequest::local, expectedParams);
 
         Request request = IndicesRequestConverters.getFieldMapping(getFieldMappingsRequest);
         StringJoiner endpoint = new StringJoiner("/", "/", "");

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java

@@ -706,7 +706,6 @@ public class IndicesClientDocumentationIT extends ESRestHighLevelClientTestCase
         // end::get-field-mappings-request-local
 
         {
-
             // tag::get-field-mappings-execute
             GetFieldMappingsResponse response =
                 client.indices().getFieldMapping(request, RequestOptions.DEFAULT);

docs/java-rest/high-level/indices/get_field_mappings.asciidoc

@@ -34,7 +34,8 @@ how wildcard expressions are expanded
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-request-local]
 --------------------------------------------------
-<1> The `local` flag (defaults to `false`) controls whether the aliases need
+<1> deprecated:[7.8.0, This parameter is a no-op and field mappings are always retrieved locally]
+The `local` flag (defaults to `false`) controls whether the aliases need
 to be looked up in the local cluster state or in the cluster state held by
 the elected master node
 

docs/reference/indices/get-field-mapping.asciidoc

@@ -48,7 +48,11 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
 (Optional, boolean) If `true`, the response includes default mapping values.
 Defaults to `false`.
 
-include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
+`local`::
+deprecated:[7.8.0, This parameter is a no-op and field mappings are always retrieved locally]
+(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.
 
 
 [[get-field-mapping-api-example]]

rest-api-spec/src/main/resources/rest-api-spec/test/indices.get_field_mapping/10_basic.yml

@@ -50,3 +50,20 @@ setup:
 
   - match: {test_index.mappings.text.mapping.text.type:     text}
   - match: {test_index.mappings.text.mapping.text.analyzer: default}
+
+---
+"Get field mapping with local is deprecated":
+
+  - skip:
+      features: ["warnings", "node_selector"]
+
+  - do:
+      node_selector:
+        version: "8.0.0 - "
+      warnings:
+        - "Use [local] in get field mapping requests is deprecated. The parameter will be removed in the next major version"
+      indices.get_field_mapping:
+        fields: text
+        local: true
+
+  - match: {test_index.mappings.text.mapping.text.type:     text}

server/src/main/java/org/elasticsearch/rest/action/admin/indices/RestGetFieldMappingAction.java

@@ -19,12 +19,15 @@
 
 package org.elasticsearch.rest.action.admin.indices;
 
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
 import org.elasticsearch.action.admin.indices.mapping.get.GetFieldMappingsRequest;
 import org.elasticsearch.action.admin.indices.mapping.get.GetFieldMappingsResponse;
 import org.elasticsearch.action.admin.indices.mapping.get.GetFieldMappingsResponse.FieldMappingMetadata;
 import org.elasticsearch.action.support.IndicesOptions;
 import org.elasticsearch.client.node.NodeClient;
 import org.elasticsearch.common.Strings;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 import org.elasticsearch.rest.BaseRestHandler;
 import org.elasticsearch.rest.BytesRestResponse;
@@ -43,6 +46,10 @@ import static org.elasticsearch.rest.RestStatus.OK;
 
 public class RestGetFieldMappingAction extends BaseRestHandler {
 
+    private static final Logger logger = LogManager.getLogger(RestGetFieldMappingAction.class);
+    private static final DeprecationLogger deprecationLogger = new DeprecationLogger(logger);
+
+
     @Override
     public List<Route> routes() {
         return List.of(
@@ -63,6 +70,12 @@ public class RestGetFieldMappingAction extends BaseRestHandler {
         GetFieldMappingsRequest getMappingsRequest = new GetFieldMappingsRequest();
         getMappingsRequest.indices(indices).fields(fields).includeDefaults(request.paramAsBoolean("include_defaults", false));
         getMappingsRequest.indicesOptions(IndicesOptions.fromRequest(request, getMappingsRequest.indicesOptions()));
+
+        if (request.hasParam("local")) {
+            deprecationLogger.deprecatedAndMaybeLog("get_field_mapping_local",
+                "Use [local] in get field mapping requests is deprecated. "
+                    + "The parameter will be removed in the next major version");
+        }
         getMappingsRequest.local(request.paramAsBoolean("local", getMappingsRequest.local()));
         return channel ->
                 client.admin().indices().getFieldMappings(getMappingsRequest, new RestBuilderListener<>(channel) {