In the field capabilities API, deprecate support for providing fields…

… in the request body. (#30157)

docs/reference/migration/index.asciidoc

@@ -26,3 +26,5 @@ include::migrate_6_1.asciidoc[]
 include::migrate_6_2.asciidoc[]
 
 include::migrate_6_3.asciidoc[]
+
+include::migrate_6_4.asciidoc[]

docs/reference/migration/migrate_6_4.asciidoc

@@ -0,0 +1,12 @@
+[[breaking-changes-6.4]]
+== Breaking changes in 6.4
+
+[[breaking_64_api_changes]]
+=== API changes
+
+==== Field capabilities request format
+
+In the past, `fields` could be provided either as a parameter, or as part of the request
+body. Specifying `fields` in the request body is now deprecated, and instead they should
+always be supplied through a request parameter. In 7.0.0, the field capabilities API will
+not accept `fields` supplied in the request body.

docs/reference/search/field-caps.asciidoc

@@ -20,7 +20,7 @@ GET twitter/_field_caps?fields=rating
 // CONSOLE
 // TEST[setup:twitter]
 
-Alternatively the `fields` option can also be defined in the request body:
+Alternatively the `fields` option can also be defined in the request body. deprecated[6.4.0, Please use a request parameter instead.]
 
 [source,js]
 --------------------------------------------------
@@ -30,6 +30,7 @@ POST _field_caps
 }
 --------------------------------------------------
 // CONSOLE
+// TEST[warning:Specifying a request body is deprecated -- the [fields] request parameter should be used instead.]
 
 This is equivalent to the previous request.
 

server/src/main/java/org/elasticsearch/rest/action/RestFieldCapabilitiesAction.java

@@ -57,11 +57,16 @@ public String getName() {
     @Override
     public RestChannelConsumer prepareRequest(final RestRequest request,
                                               final NodeClient client) throws IOException {
-        if (request.hasContentOrSourceParam() && request.hasParam("fields")) {
-            throw new IllegalArgumentException("can't specify a request body and [fields]" +
-                " request parameter, either specify a request body or the" +
-                " [fields] request parameter");
+        if (request.hasContentOrSourceParam()) {
+            deprecationLogger.deprecated("Specifying a request body is deprecated -- the" +
+                " [fields] request parameter should be used instead.");
+            if (request.hasParam("fields")) {
+                throw new IllegalArgumentException("can't specify a request body and [fields]" +
+                    " request parameter, either specify a request body or the" +
+                    " [fields] request parameter");
+            }
         }
+
         final String[] indices = Strings.splitStringByCommaToArray(request.param("index"));
         final FieldCapabilitiesRequest fieldRequest;
         if (request.hasContentOrSourceParam()) {

server/src/test/java/org/elasticsearch/rest/action/RestFieldCapabilitiesActionTests.java

@@ -0,0 +1,59 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.rest.action;
+
+import org.elasticsearch.client.node.NodeClient;
+import org.elasticsearch.common.bytes.BytesArray;
+import org.elasticsearch.common.settings.Settings;
+import org.elasticsearch.common.xcontent.XContentType;
+import org.elasticsearch.rest.RestController;
+import org.elasticsearch.rest.RestRequest;
+import org.elasticsearch.rest.action.RestFieldCapabilitiesAction;
+import org.elasticsearch.test.ESTestCase;
+import org.elasticsearch.test.rest.FakeRestRequest;
+import org.elasticsearch.usage.UsageService;
+import org.junit.Before;
+
+import java.io.IOException;
+import java.util.Collections;
+
+import static org.mockito.Mockito.mock;
+
+public class RestFieldCapabilitiesActionTests extends ESTestCase {
+
+    private RestFieldCapabilitiesAction action;
+
+    @Before
+    public void setUpAction() {
+        action = new RestFieldCapabilitiesAction(Settings.EMPTY, mock(RestController.class));
+    }
+
+    public void testRequestBodyIsDeprecated() throws IOException {
+        String content = "{ \"fields\": [\"title\"] }";
+        RestRequest request = new FakeRestRequest.Builder(xContentRegistry())
+            .withPath("/_field_caps")
+            .withContent(new BytesArray(content), XContentType.JSON)
+            .build();
+        action.prepareRequest(request, mock(NodeClient.class));
+
+        assertWarnings("Specifying a request body is deprecated -- the" +
+            " [fields] request parameter should be used instead.");
+    }
+}