Deprecating request parameters of _analyze API in 5.x

core/src/main/java/org/elasticsearch/rest/action/admin/indices/RestAnalyzeAction.java

@@ -65,44 +65,73 @@ public RestAnalyzeAction(Settings settings, RestController controller) {
         controller.registerHandler(POST, "/{index}/_analyze", this);
     }
 
+    private void deprecationLog(String key, RestRequest request) {
+        if (request.hasParam(key)) {
+            deprecationLogWithoutCheck(key);
+        }
+    }
+
+    private void deprecationLogWithoutCheck(String key) {
+        deprecationLogForText(key + " request parameter is deprecated and will be removed in the next major release." +
+            " Please use the JSON in the request body instead request param");
+    }
+
+    void deprecationLogForText(String msg) {
+        deprecationLogger.deprecated(msg);
+    }
+
     @Override
     public void handleRequest(final RestRequest request, final RestChannel channel, final NodeClient client) {
 
         String[] texts = request.paramAsStringArrayOrEmptyIfAll("text");
+        deprecationLog("text", request);
 
         AnalyzeRequest analyzeRequest = new AnalyzeRequest(request.param("index"));
         analyzeRequest.text(texts);
         analyzeRequest.analyzer(request.param("analyzer"));
+        deprecationLog("analyzer", request);
         analyzeRequest.field(request.param("field"));
+        deprecationLog("field", request);
         if (request.hasParam("tokenizer")) {
             analyzeRequest.tokenizer(request.param("tokenizer"));
+            deprecationLogWithoutCheck("tokenizer");
         }
         for (String filter : request.paramAsStringArray("filter", Strings.EMPTY_ARRAY)) {
             analyzeRequest.addTokenFilter(filter);
+            deprecationLogWithoutCheck("filter");
         }
         for (String charFilter : request.paramAsStringArray("char_filter", Strings.EMPTY_ARRAY)) {
             analyzeRequest.addTokenFilter(charFilter);
+            deprecationLogWithoutCheck("char_filter");
         }
         analyzeRequest.explain(request.paramAsBoolean("explain", false));
+        deprecationLog("explain", request);
         analyzeRequest.attributes(request.paramAsStringArray("attributes", analyzeRequest.attributes()));
+        deprecationLog("attributes", request);
 
+        handleBodyContent(request, texts, analyzeRequest);
+
+        client.admin().indices().analyze(analyzeRequest, new RestToXContentListener<>(channel));
+    }
+
+    void handleBodyContent(RestRequest request, String[] texts, AnalyzeRequest analyzeRequest) {
         if (RestActions.hasBodyContent(request)) {
             XContentType type = RestActions.guessBodyContentType(request);
             if (type == null) {
                 if (texts == null || texts.length == 0) {
                     texts = new String[]{ RestActions.getRestContent(request).utf8ToString() };
                     analyzeRequest.text(texts);
+                    deprecationLogForText(" plain text bodies is deprecated and " +
+                        "this feature will be removed in the next major release. Please use the text param in JSON");
                 }
             } else {
                 // NOTE: if rest request with xcontent body has request parameters, the parameters does not override xcontent values
                 buildFromContent(RestActions.getRestContent(request), analyzeRequest, parseFieldMatcher);
             }
         }
-
-        client.admin().indices().analyze(analyzeRequest, new RestToXContentListener<>(channel));
     }
 
-    public static void buildFromContent(BytesReference content, AnalyzeRequest analyzeRequest, ParseFieldMatcher parseFieldMatcher) {
+    static void buildFromContent(BytesReference content, AnalyzeRequest analyzeRequest, ParseFieldMatcher parseFieldMatcher) {
         try (XContentParser parser = XContentHelper.createParser(content)) {
             if (parser.nextToken() != XContentParser.Token.START_OBJECT) {
                 throw new IllegalArgumentException("Malformed content, must start with an object");

core/src/test/java/org/elasticsearch/rest/action/admin/indices/RestAnalyzeActionTests.java

@@ -19,16 +19,25 @@
 package org.elasticsearch.rest.action.admin.indices;
 
 import org.elasticsearch.action.admin.indices.analyze.AnalyzeRequest;
+import org.elasticsearch.client.node.NodeClient;
 import org.elasticsearch.common.ParseFieldMatcher;
 import org.elasticsearch.common.bytes.BytesArray;
 import org.elasticsearch.common.bytes.BytesReference;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.xcontent.XContentFactory;
+import org.elasticsearch.rest.RestChannel;
+import org.elasticsearch.rest.RestRequest;
 import org.elasticsearch.test.ESTestCase;
+import org.elasticsearch.test.rest.FakeRestRequest;
+
+import java.util.HashMap;
 
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.notNullValue;
 import static org.hamcrest.Matchers.startsWith;
+import static org.mockito.Mockito.doCallRealMethod;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
 
 public class RestAnalyzeActionTests extends ESTestCase {
 
@@ -118,7 +127,7 @@ public void testParseXContentForAnalyzeRequestWithInvalidStringExplainParamThrow
         assertThat(e.getMessage(), startsWith("explain must be either 'true' or 'false'"));
     }
 
-    public void testDeprecatedParamException() throws Exception {
+    public void testDeprecatedParamIn2xException() throws Exception {
         IllegalArgumentException e = expectThrows(IllegalArgumentException.class,
             () -> RestAnalyzeAction.buildFromContent(
                 XContentFactory.jsonBuilder()
@@ -166,4 +175,24 @@ public void testDeprecatedParamException() throws Exception {
         assertThat(e.getMessage(), startsWith("Unknown parameter [token_filter]"));
     }
 
+    public void testDeprecatedReqParamsIn5x() throws Exception {
+        RestAnalyzeAction action = mock(RestAnalyzeAction.class);
+        AnalyzeRequest analyzeRequest = new AnalyzeRequest();
+
+        BytesReference content = new BytesArray("this is test");
+        FakeRestRequest request = new FakeRestRequest.Builder()
+            .withContent(content)
+            .withMethod(randomFrom(RestRequest.Method.values()))
+            .build();
+
+        doCallRealMethod().when(action).handleBodyContent(request, null, analyzeRequest);
+
+        action.handleBodyContent(request, null, analyzeRequest);
+        verify(action).deprecationLogForText(" plain text bodies is deprecated and " +
+            "this feature will be removed in the next major release. Please use the text param in JSON");
+        assertThat(analyzeRequest.text().length, equalTo(1));
+        assertThat(analyzeRequest.text()[0], equalTo("this is test"));
+
+    }
+
 }

docs/plugins/analysis-icu.asciidoc

@@ -164,7 +164,11 @@ PUT icu_sample
     }
 }
 
-POST icu_sample/_analyze?analyzer=my_analyzer&text=Elasticsearch. Wow!
+POST icu_sample/_analyze
+{
+  "analyzer": "my_analyzer",
+  "text": "Elasticsearch. Wow!"
+}
 --------------------------------------------------
 // CONSOLE
 
@@ -480,18 +484,21 @@ PUT icu_sample
   }
 }
 
-GET icu_sample/_analyze?analyzer=latin
+GET icu_sample/_analyze
 {
+  "analyzer": "latin",
   "text": "你好" <2>
 }
 
-GET icu_sample/_analyze?analyzer=latin
+GET icu_sample/_analyze
 {
+  "analyzer": "latin",
   "text": "здравствуйте" <3>
 }
 
-GET icu_sample/_analyze?analyzer=latin
+GET icu_sample/_analyze
 {
+  "analyzer": "latin",
   "text": "こんにちは" <4>
 }
 

docs/plugins/analysis-kuromoji.asciidoc

@@ -175,7 +175,11 @@ PUT kuromoji_sample
   }
 }
 
-POST kuromoji_sample/_analyze?analyzer=my_analyzer&text=東京スカイツリー
+POST kuromoji_sample/_analyze
+{
+  "analyzer": "my_analyzer",
+  "text": "東京スカイツリー"
+}
 --------------------------------------------------
 // CONSOLE
 
@@ -228,7 +232,11 @@ PUT kuromoji_sample
   }
 }
 
-POST kuromoji_sample/_analyze?analyzer=my_analyzer&text=飲み
+POST kuromoji_sample/_analyze
+{
+  "analyzer": "my_analyzer",
+  "text": "飲み"
+}
 --------------------------------------------------
 // CONSOLE
 
@@ -290,7 +298,11 @@ PUT kuromoji_sample
   }
 }
 
-POST kuromoji_sample/_analyze?analyzer=my_analyzer&text=寿司がおいしいね
+POST kuromoji_sample/_analyze
+{
+  "analyzer": "my_analyzer",
+  "text": "寿司がおいしいね"
+}
 --------------------------------------------------
 // CONSOLE
 
@@ -363,9 +375,17 @@ PUT kuromoji_sample
     }
 }
 
-POST kuromoji_sample/_analyze?analyzer=katakana_analyzer&text=寿司 <1>
+POST kuromoji_sample/_analyze
+{
+  "analyzer": "katakana_analyzer",
+  "text": "寿司" <1>
+}
 
-POST kuromoji_sample/_analyze?analyzer=romaji_analyzer&text=寿司 <2>
+POST kuromoji_sample/_analyze
+{
+  "analyzer": "romaji_analyzer",
+  "text": "寿司" <2>
+}
 --------------------------------------------------
 // CONSOLE
 
@@ -413,9 +433,17 @@ PUT kuromoji_sample
   }
 }
 
-POST kuromoji_sample/_analyze?analyzer=my_analyzer&text=コピー <1>
+POST kuromoji_sample/_analyze
+{
+  "analyzer": "my_analyzer",
+  "text": "コピー" <1>
+}
 
-POST kuromoji_sample/_analyze?analyzer=my_analyzer&text=サーバー <2>
+POST kuromoji_sample/_analyze
+{
+  "analyzer": "my_analyzer",
+  "text": "サーバー" <2>
+}
 --------------------------------------------------
 // CONSOLE
 
@@ -461,7 +489,11 @@ PUT kuromoji_sample
   }
 }
 
-POST kuromoji_sample/_analyze?analyzer=analyzer_with_ja_stop&text=ストップは消える
+POST kuromoji_sample/_analyze
+{
+  "analyzer": "analyzer_with_ja_stop",
+  "text": "ストップは消える"
+}
 --------------------------------------------------
 // CONSOLE
 
@@ -507,7 +539,11 @@ PUT kuromoji_sample
   }
 }
 
-POST kuromoji_sample/_analyze?analyzer=my_analyzer&text=一〇〇〇
+POST kuromoji_sample/_analyze
+{
+  "analyzer": "my_analyzer",
+  "text": "一〇〇〇"
+}
 --------------------------------------------------
 // CONSOLE
 

docs/plugins/analysis-phonetic.asciidoc

@@ -82,7 +82,11 @@ PUT phonetic_sample
   }
 }
 
-POST phonetic_sample/_analyze?analyzer=my_analyzer&text=Joe Bloggs <1>
+POST phonetic_sample/_analyze
+{
+  "analyzer": "my_analyzer",
+  "text": "Joe Bloggs" <1>
+}
 --------------------------------------------------
 // CONSOLE
 

docs/reference/indices/analyze.asciidoc

@@ -100,6 +100,7 @@ curl -XGET 'localhost:9200/test/_analyze' -d '
 Will cause the analysis to happen based on the analyzer configured in the
 mapping for `obj1.field1` (and if not, the default index analyzer).
 
+[deprecated 5.1.0 request parameters are deprecated and will be removed in the next major release. please use JSON params instead of request params]
 All parameters can also supplied as request parameters. For example:
 
 [source,js]
@@ -115,6 +116,8 @@ provided it doesn't start with `{` :
 curl -XGET 'localhost:9200/_analyze?tokenizer=keyword&filter=lowercase&char_filter=html_strip' -d 'this is a <b>test</b>'
 --------------------------------------------------
 
+[deprecated 5.1.0 the text parameter as the body of the request are deprecated and this feature will be removed in the next major release. please use JSON text param]
+
 === Explain Analyze
 
 If you want to get more advanced details, set `explain` to `true` (defaults to `false`). It will output all token attributes for each token.

docs/reference/mapping/params/analyzer.asciidoc

@@ -60,13 +60,15 @@ PUT /my_index
   }
 }
 
-GET my_index/_analyze?field=text <3>
+GET my_index/_analyze <3>
 {
+  "field": "text",
   "text": "The quick Brown Foxes."
 }
 
-GET my_index/_analyze?field=text.english <4>
+GET my_index/_analyze <4>
 {
+  "field": "text.english",
   "text": "The quick Brown Foxes."
 }
 --------------------------------------------------

plugins/analysis-icu/src/test/resources/rest-api-spec/test/analysis_icu/10_basic.yaml

@@ -2,6 +2,9 @@
 #
 "Tokenizer":
     - do:
+        warnings:
+          - text request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
+          - tokenizer request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
         indices.analyze:
           text:         Foo Bar
           tokenizer:    icu_tokenizer
@@ -11,6 +14,10 @@
 ---
 "Normalization filter":
     - do:
+        warnings:
+          - filter request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
+          - text request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
+          - tokenizer request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
         indices.analyze:
           filter:      icu_normalizer
           text:         Foo Bar Ruß
@@ -20,6 +27,10 @@
 ---
 "Normalization charfilter":
     - do:
+        warnings:
+          - char_filter request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
+          - text request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
+          - tokenizer request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
         indices.analyze:
           char_filter: icu_normalizer
           text:         Foo Bar Ruß
@@ -29,6 +40,10 @@
 ---
 "Folding filter":
     - do:
+        warnings:
+          - filter request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
+          - text request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
+          - tokenizer request parameter is deprecated and will be removed in the next major release. Please use the JSON in the request body instead request param
         indices.analyze:
           filter:      icu_folding
           text:         Foo Bar résumé