Deprecate _knn_search in the REST spec (#94103) (#94288)

We deprecated the _knn_search endpoint with #88828 but we missed deprecating it in the REST spec.

Note that the REST spec parser was not aligned with its json schema in that the deprecated section caused an exception to be thrown. The parser is now updated to accept the deprecated section at the endpoint level.

rest-api-spec/src/main/resources/rest-api-spec/api/knn_search.json

@@ -5,6 +5,10 @@
       "description":"Performs a kNN search."
     },
     "stability":"experimental",
+    "deprecated" : {
+      "version" : "8.4.0",
+      "description" : "The kNN search API has been replaced by the `knn` option in the search API."
+    },
     "visibility":"public",
     "headers":{
       "accept": [ "application/json"],

test/yaml-rest-runner/src/main/java/org/elasticsearch/test/rest/yaml/restspec/ClientYamlSuiteRestApi.java

@@ -28,12 +28,13 @@ public class ClientYamlSuiteRestApi {
 
     private final String location;
     private final String name;
-    private Set<Path> paths = new LinkedHashSet<>();
-    private Map<String, Boolean> params = new HashMap<>();
+    private final Set<Path> paths = new LinkedHashSet<>();
+    private final Map<String, Boolean> params = new HashMap<>();
     private Body body = Body.NOT_SUPPORTED;
     private Stability stability;
     private Visibility visibility;
     private String featureFlag;
+
     private List<String> responseMimeTypes;
     private List<String> requestMimeTypes;
 

test/yaml-rest-runner/src/main/java/org/elasticsearch/test/rest/yaml/restspec/ClientYamlSuiteRestApiParser.java

@@ -86,6 +86,14 @@ public ClientYamlSuiteRestApi parse(String location, XContentParser parser) thro
                 } else if ("feature_flag".equals(parser.currentName())) {
                     parser.nextToken();
                     restApi.setFeatureFlag(parser.textOrNull());
+                } else if ("deprecated".equals(parser.currentName())) {
+                    if (parser.nextToken() != XContentParser.Token.START_OBJECT) {
+                        throw new ParsingException(
+                            parser.getTokenLocation(),
+                            apiName + " API: expected [deprecated] field in rest api definition to hold an object"
+                        );
+                    }
+                    parser.skipChildren();
                 } else if ("url".equals(parser.currentName())) {
                     String currentFieldName = null;
                     assert parser.nextToken() == XContentParser.Token.START_OBJECT;

test/yaml-rest-runner/src/test/java/org/elasticsearch/test/rest/yaml/restspec/ClientYamlSuiteRestApiParserFailingTests.java

@@ -88,6 +88,14 @@ public void testBrokenSpecShouldThrowUsefulExceptionWhenParsingFailsOnParams() t
         );
     }
 
+    public void testBrokenSpecShouldThrowUsefulExceptionWhenParsingFailsOnDeprecated() throws Exception {
+        parseAndExpectParsingException(
+            BROKEN_DEPRECATED_DEF,
+            "indices.get_template.json",
+            "indices.get_template API: expected [deprecated] field in rest api definition to hold an object"
+        );
+    }
+
     public void testBrokenSpecShouldThrowUsefulExceptionWhenParsingFailsOnParts() throws Exception {
         parseAndExpectParsingException(
             BROKEN_SPEC_PARTS,
@@ -164,4 +172,42 @@ private void parseAndExpectIllegalArgumentException(String brokenJson, String lo
             }
           }
         """;
+
+    // deprecated needs to be an object
+    private static final String BROKEN_DEPRECATED_DEF = """
+        {
+          "indices.get_template":{
+            "documentation":{
+              "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates.html",
+              "description":"Returns an index template."
+            },
+            "headers": { "accept": ["application/json"] },
+            "stability": "stable",
+            "visibility": "public",
+            "deprecated" : true,
+            "url":{
+              "paths":[
+                {
+                  "path":"/_template",
+                  "methods":[
+                    "GET"
+                  ]
+                },
+                {
+                  "path":"/_template/{name}",
+                  "methods":[
+                    "GET"
+                  ],
+                  "parts":{
+                    "name":{
+                      "type":"list",
+                      "description":"The comma separated names of the index templates"
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        }
+        """;
 }

test/yaml-rest-runner/src/test/java/org/elasticsearch/test/rest/yaml/restspec/ClientYamlSuiteRestApiParserTests.java

@@ -156,6 +156,35 @@ public void testRequiredBodyWithoutUrlParts() throws Exception {
         assertThat(restApi.isBodyRequired(), equalTo(true));
     }
 
+    public void testParseRestSpecDeprecatedApi() throws Exception {
+        parser = createParser(YamlXContent.yamlXContent, REST_SPEC_DEPRECATED_ENDPOINT);
+        ClientYamlSuiteRestApi restApi = new ClientYamlSuiteRestApiParser().parse("indices.get_template.json", parser);
+        assertThat(restApi, notNullValue());
+        assertThat(restApi.getName(), equalTo("indices.get_template"));
+        assertThat(restApi.getPaths().size(), equalTo(2));
+        Iterator<ClientYamlSuiteRestApi.Path> iterator = restApi.getPaths().iterator();
+        {
+            ClientYamlSuiteRestApi.Path next = iterator.next();
+            assertThat(next.path(), equalTo("/_template"));
+            assertThat(next.methods().length, equalTo(1));
+            assertThat(next.methods()[0], equalTo("GET"));
+            assertEquals(0, next.parts().size());
+        }
+        {
+            ClientYamlSuiteRestApi.Path next = iterator.next();
+            assertThat(next.path(), equalTo("/_template/{name}"));
+            assertThat(next.methods().length, equalTo(1));
+            assertThat(next.methods()[0], equalTo("GET"));
+            assertThat(next.parts().size(), equalTo(1));
+            assertThat(next.parts(), contains("name"));
+        }
+        assertThat(restApi.getParams().size(), equalTo(0));
+        assertThat(restApi.isBodySupported(), equalTo(false));
+        assertThat(restApi.isBodyRequired(), equalTo(false));
+        assertThat(restApi.getRequestMimeTypes(), nullValue());
+        assertThat(restApi.getResponseMimeTypes(), containsInAnyOrder("application/json"));
+    }
+
     private static final String REST_SPEC_COUNT_API = """
         {
           "count":{
@@ -353,4 +382,44 @@ public void testRequiredBodyWithoutUrlParts() throws Exception {
           }
         }
         """;
+
+    private static final String REST_SPEC_DEPRECATED_ENDPOINT = """
+        {
+          "indices.get_template":{
+            "documentation":{
+              "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates.html",
+              "description":"Returns an index template."
+            },
+            "headers": { "accept": ["application/json"] },
+            "stability": "stable",
+            "visibility": "public",
+            "deprecated" : {
+              "description" : "deprecated api",
+              "version" : "8.4.0"
+            },
+            "url":{
+              "paths":[
+                {
+                  "path":"/_template",
+                  "methods":[
+                    "GET"
+                  ]
+                },
+                {
+                  "path":"/_template/{name}",
+                  "methods":[
+                    "GET"
+                  ],
+                  "parts":{
+                    "name":{
+                      "type":"list",
+                      "description":"The comma separated names of the index templates"
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        }
+        """;
 }