Introduce stability description to the REST API specification (#38413) (#43278)

* introduce state to the REST API specification

* change state over to stability

* CCR is no GA updated to stable

* SQL is now GA so marked as stable

* Introduce `internal` as state for API's, marks stable in terms of lifetime but unstable in terms of guarantees on its output format since it exposes internal representations

* make setting a wrong stability value, or not setting it at all an error that causes the YAML test suite to fail

* update spec files to be explicit about their stability state

* Document the fact that stability needs to be defined

Otherwise the YAML test runner will fail (with a nice exception message)

* address check style violations

* update rest spec unit tests to include stability

* found one more test spec file not declaring stability, made sure stability appears after documentation everywhere

* cluster.state is stable, mark response in some way to denote its a key value format that can be changed during minors

* mark data frame API's as beta

* remove internal and private as states for an API

* removed the wrong enum values in the Stability Enum in the previous commit

(cherry picked from commit 61c34bbd92f8f7e5f22fa411c6b682b0ebd8a99d)

modules/lang-painless/src/test/resources/rest-api-spec/api/scripts_painless_context.json

@@ -1,5 +1,6 @@
 {
   "scripts_painless_context": {
+    "stability": "experimental",
     "methods": ["GET"],
     "url": {
       "paths": ["/_scripts/painless/_context"],

plugins/examples/rest-handler/src/test/resources/rest-api-spec/api/cat.example.json

@@ -1,6 +1,7 @@
 {
   "cat.example": {
     "documentation": "",
+    "stability" : "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/example"],

rest-api-spec/README.markdown

@@ -10,6 +10,7 @@ Example for the ["Create Index"](http://www.elastic.co/guide/en/elasticsearch/re
 {
   "indices.create": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-create-index.html",
+    "stability": "stable",
     "methods": ["PUT", "POST"],
     "url": {
       "paths": ["/{index}"],
@@ -38,10 +39,30 @@ The specification contains:
 
 * The _name_ of the API (`indices.create`), which usually corresponds to the client calls
 * Link to the documentation at <http://elastic.co>
+* `stability` indicating the state of the API, has to be declared explicitly or YAML tests will fail
+    * `experimental` highly likely to break in the near future (minor/path), no bwc guarantees. 
+    Possibly removed in the future.
+    * `beta` less likely to break or be removed but still reserve the right to do so
+    * `stable` No backwards breaking changes in a minor 
 * List of HTTP methods for the endpoint
 * URL specification: path, parts, parameters
 * Whether body is allowed for the endpoint or not and its description
 
+**NOTE** 
+If an API is stable but it response should be treated as an arbitrary map of key values please notate this as followed
+
+```json
+{
+  "api.name": {
+    "stability" : "stable",
+    "response": {
+      "treat_json_as_key_value" : true
+    }
+  }
+}
+```
+
+
 The `methods` and `url.paths` elements list all possible HTTP methods and URLs for the endpoint;
 it is the responsibility of the developer to use this information for a sensible API on the target platform.
 

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

@@ -1,6 +1,7 @@
 {
   "bulk": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html",
+    "stability": "stable",
     "methods": ["POST", "PUT"],
     "url": {
       "paths": ["/_bulk", "/{index}/_bulk", "/{index}/{type}/_bulk"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.aliases.json

@@ -1,6 +1,7 @@
 {
   "cat.aliases": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-alias.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/aliases", "/_cat/aliases/{name}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.allocation.json

@@ -1,6 +1,7 @@
 {
   "cat.allocation": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-allocation.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/allocation", "/_cat/allocation/{node_id}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.count.json

@@ -1,6 +1,7 @@
 {
   "cat.count": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-count.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/count", "/_cat/count/{index}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.fielddata.json

@@ -1,6 +1,7 @@
 {
   "cat.fielddata": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-fielddata.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/fielddata", "/_cat/fielddata/{fields}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.health.json

@@ -1,6 +1,7 @@
 {
   "cat.health": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-health.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/health"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.help.json

@@ -1,6 +1,7 @@
 {
   "cat.help": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.indices.json

@@ -1,6 +1,7 @@
 {
   "cat.indices": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-indices.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/indices", "/_cat/indices/{index}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.master.json

@@ -1,6 +1,7 @@
 {
   "cat.master": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-master.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/master"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.nodeattrs.json

@@ -1,6 +1,7 @@
 {
   "cat.nodeattrs": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-nodeattrs.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/nodeattrs"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.nodes.json

@@ -1,6 +1,7 @@
 {
   "cat.nodes": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-nodes.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/nodes"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.pending_tasks.json

@@ -1,6 +1,7 @@
 {
   "cat.pending_tasks": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-pending-tasks.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/pending_tasks"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.plugins.json

@@ -1,6 +1,7 @@
 {
   "cat.plugins": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-plugins.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/plugins"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.recovery.json

@@ -1,6 +1,7 @@
 {
   "cat.recovery": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-recovery.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/recovery", "/_cat/recovery/{index}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.repositories.json

@@ -1,6 +1,7 @@
 {
   "cat.repositories": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-repositories.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/repositories"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.segments.json

@@ -1,6 +1,7 @@
 {
   "cat.segments": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-segments.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/segments", "/_cat/segments/{index}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.shards.json

@@ -1,6 +1,7 @@
 {
   "cat.shards": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-shards.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/shards", "/_cat/shards/{index}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.snapshots.json

@@ -1,6 +1,7 @@
 {
   "cat.snapshots": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-snapshots.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": [

rest-api-spec/src/main/resources/rest-api-spec/api/cat.tasks.json

@@ -1,6 +1,7 @@
 {
   "cat.tasks": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/tasks.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/tasks"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.templates.json

@@ -1,6 +1,7 @@
 {
   "cat.templates": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-templates.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/templates", "/_cat/templates/{name}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cat.thread_pool.json

@@ -1,6 +1,7 @@
 {
   "cat.thread_pool": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cat-thread-pool.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cat/thread_pool","/_cat/thread_pool/{thread_pool_patterns}"],

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

@@ -1,6 +1,7 @@
 {
   "clear_scroll": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/search-request-scroll.html",
+    "stability": "stable",
     "methods": ["DELETE"],
     "url": {
       "paths": [ "/_search/scroll"],

rest-api-spec/src/main/resources/rest-api-spec/api/cluster.allocation_explain.json

@@ -1,6 +1,7 @@
 {
   "cluster.allocation_explain": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-allocation-explain.html",
+    "stability": "stable",
     "methods": ["GET", "POST"],
     "url": {
       "paths": ["/_cluster/allocation/explain"],

rest-api-spec/src/main/resources/rest-api-spec/api/cluster.get_settings.json

@@ -1,6 +1,7 @@
 {
   "cluster.get_settings": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-update-settings.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cluster/settings"],

rest-api-spec/src/main/resources/rest-api-spec/api/cluster.health.json

@@ -1,6 +1,7 @@
 {
   "cluster.health": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-health.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cluster/health", "/_cluster/health/{index}"],

rest-api-spec/src/main/resources/rest-api-spec/api/cluster.pending_tasks.json

@@ -1,6 +1,7 @@
 {
   "cluster.pending_tasks": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-pending.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cluster/pending_tasks"],

rest-api-spec/src/main/resources/rest-api-spec/api/cluster.put_settings.json

@@ -1,6 +1,7 @@
 {
   "cluster.put_settings": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-update-settings.html",
+    "stability": "stable",
     "methods": ["PUT"],
     "url": {
       "paths": ["/_cluster/settings"],

rest-api-spec/src/main/resources/rest-api-spec/api/cluster.remote_info.json

@@ -1,6 +1,7 @@
 {
   "cluster.remote_info": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-remote-info.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_remote/info"],

rest-api-spec/src/main/resources/rest-api-spec/api/cluster.reroute.json

@@ -1,6 +1,7 @@
 {
   "cluster.reroute": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-reroute.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/_cluster/reroute"],

rest-api-spec/src/main/resources/rest-api-spec/api/cluster.state.json

@@ -1,6 +1,7 @@
 {
   "cluster.state": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-state.html",
+    "stability" : "stable",
     "methods": ["GET"],
     "url": {
       "paths": [
@@ -56,6 +57,9 @@
         }
       }
     },
-    "body": null
+    "body": null,
+    "response": {
+      "treat_json_as_key_value" : true
+    }
   }
 }

rest-api-spec/src/main/resources/rest-api-spec/api/cluster.stats.json

@@ -1,6 +1,7 @@
 {
   "cluster.stats": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-stats.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_cluster/stats", "/_cluster/stats/nodes/{node_id}"],

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

@@ -1,6 +1,7 @@
 {
   "count": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/search-count.html",
+    "stability": "stable",
     "methods": ["POST", "GET"],
     "url": {
       "paths": ["/_count", "/{index}/_count"],

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

@@ -1,6 +1,7 @@
 {
   "create": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-index_.html",
+    "stability": "stable",
     "methods": ["PUT","POST"],
     "url": {
       "paths": ["/{index}/_create/{id}"],

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

@@ -1,6 +1,7 @@
 {
   "delete": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-delete.html",
+    "stability": "stable",
     "methods": ["DELETE"],
     "url": {
       "paths": ["/{index}/_doc/{id}"],

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

@@ -1,6 +1,7 @@
 {
   "delete_by_query": {
     "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-delete-by-query.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/{index}/_delete_by_query"],

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

@@ -1,6 +1,7 @@
 {
   "delete_by_query_rethrottle": {
     "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/_delete_by_query/{task_id}/_rethrottle"],

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

@@ -1,6 +1,7 @@
 {
   "delete_script": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html",
+    "stability": "stable",
     "methods": ["DELETE"],
     "url": {
       "paths": [ "/_scripts/{id}" ],

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

@@ -1,6 +1,7 @@
 {
   "exists": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html",
+    "stability": "stable",
     "methods": ["HEAD"],
     "url": {
       "paths": ["/{index}/_doc/{id}"],

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

@@ -1,6 +1,7 @@
 {
   "exists_source": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html",
+    "stability": "stable",
     "methods": ["HEAD"],
     "url": {
       "paths": ["/{index}/_source/{id}"],

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

@@ -1,6 +1,7 @@
 {
   "explain": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/search-explain.html",
+    "stability": "stable",
     "methods": ["GET", "POST"],
     "url": {
       "paths": ["/{index}/_explain/{id}"],

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

@@ -1,6 +1,7 @@
 {
   "field_caps": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/search-field-caps.html",
+    "stability": "stable",
     "methods": ["GET", "POST"],
     "url": {
       "paths": [

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

@@ -1,6 +1,7 @@
 {
   "get": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/{index}/_doc/{id}"],

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

@@ -1,6 +1,7 @@
 {
   "get_script": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": [ "/_scripts/{id}" ],

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

@@ -1,6 +1,7 @@
 {
   "get_source": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-get.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/{index}/_source/{id}"],

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

@@ -1,6 +1,7 @@
 {
   "index": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-index_.html",
+    "stability": "stable",
     "methods": ["POST", "PUT"],
     "url": {
       "paths": ["/{index}/_doc/{id}", "/{index}/_doc"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.analyze.json

@@ -1,6 +1,7 @@
 {
   "indices.analyze": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-analyze.html",
+    "stability": "stable",
     "methods": ["GET", "POST"],
     "url": {
       "paths": ["/_analyze", "/{index}/_analyze"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.clear_cache.json

@@ -1,6 +1,7 @@
 {
   "indices.clear_cache": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-clearcache.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/_cache/clear", "/{index}/_cache/clear"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.close.json

@@ -1,6 +1,7 @@
 {
   "indices.close": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-open-close.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/{index}/_close"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.create.json

@@ -1,6 +1,7 @@
 {
   "indices.create": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-create-index.html",
+    "stability": "stable",
     "methods": ["PUT"],
     "url": {
       "paths": ["/{index}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.delete.json

@@ -1,6 +1,7 @@
 {
   "indices.delete": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-delete-index.html",
+    "stability": "stable",
     "methods": ["DELETE"],
     "url": {
       "paths": ["/{index}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.delete_alias.json

@@ -1,6 +1,7 @@
 {
   "indices.delete_alias": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-aliases.html",
+    "stability": "stable",
     "methods": ["DELETE"],
     "url": {
       "paths": ["/{index}/_alias/{name}", "/{index}/_aliases/{name}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.delete_template.json

@@ -1,6 +1,7 @@
 {
   "indices.delete_template": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates.html",
+    "stability": "stable",
     "methods": ["DELETE"],
     "url": {
       "paths": ["/_template/{name}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.exists.json

@@ -1,6 +1,7 @@
 {
   "indices.exists": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-exists.html",
+    "stability": "stable",
     "methods": [ "HEAD" ],
     "url": {
       "paths": [ "/{index}" ],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.exists_alias.json

@@ -1,6 +1,7 @@
 {
   "indices.exists_alias": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-aliases.html",
+    "stability": "stable",
     "methods": ["HEAD"],
     "url": {
       "paths": ["/_alias/{name}", "/{index}/_alias/{name}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.exists_template.json

@@ -1,6 +1,7 @@
 {
   "indices.exists_template": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates.html",
+    "stability": "stable",
     "methods": ["HEAD"],
     "url": {
       "paths": [ "/_template/{name}" ],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.exists_type.json

@@ -1,6 +1,7 @@
 {
   "indices.exists_type": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-types-exists.html",
+    "stability": "stable",
     "methods": ["HEAD"],
     "deprecated" : {
       "version" : "7.0.0",

rest-api-spec/src/main/resources/rest-api-spec/api/indices.flush.json

@@ -1,6 +1,7 @@
 {
   "indices.flush": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-flush.html",
+    "stability": "stable",
     "methods": ["POST", "GET"],
     "url": {
       "paths": ["/_flush", "/{index}/_flush"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.flush_synced.json

@@ -1,6 +1,7 @@
 {
   "indices.flush_synced": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-synced-flush.html",
+    "stability": "stable",
     "methods": ["POST", "GET"],
     "url": {
       "paths": [

rest-api-spec/src/main/resources/rest-api-spec/api/indices.forcemerge.json

@@ -1,6 +1,7 @@
 {
   "indices.forcemerge": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-forcemerge.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/_forcemerge", "/{index}/_forcemerge"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.get.json

@@ -1,6 +1,7 @@
 {
   "indices.get":{
     "documentation":"http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-index.html",
+    "stability": "stable",
     "methods":[ "GET" ],
     "url":{
       "paths":[ "/{index}" ],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_alias.json

@@ -1,6 +1,7 @@
 {
   "indices.get_alias": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-aliases.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": [ "/_alias", "/_alias/{name}", "/{index}/_alias/{name}", "/{index}/_alias"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_field_mapping.json

@@ -1,6 +1,7 @@
 {
   "indices.get_field_mapping": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-field-mapping.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_mapping/field/{fields}", "/{index}/_mapping/field/{fields}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_mapping.json

@@ -1,6 +1,7 @@
 {
   "indices.get_mapping": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-mapping.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_mapping", "/{index}/_mapping"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_settings.json

@@ -1,6 +1,7 @@
 {
   "indices.get_settings": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-get-settings.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_settings", "/{index}/_settings", "/{index}/_settings/{name}", "/_settings/{name}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_template.json

@@ -1,6 +1,7 @@
 {
   "indices.get_template": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": [

rest-api-spec/src/main/resources/rest-api-spec/api/indices.get_upgrade.json

@@ -1,6 +1,7 @@
 {
   "indices.get_upgrade": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-upgrade.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_upgrade", "/{index}/_upgrade"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.open.json

@@ -1,6 +1,7 @@
 {
   "indices.open": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-open-close.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/{index}/_open"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_alias.json

@@ -1,6 +1,7 @@
 {
   "indices.put_alias": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-aliases.html",
+    "stability": "stable",
     "methods": ["PUT", "POST"],
     "url": {
       "paths": ["/{index}/_alias/{name}", "/{index}/_aliases/{name}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_mapping.json

@@ -1,6 +1,7 @@
 {
   "indices.put_mapping": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-put-mapping.html",
+    "stability": "stable",
     "methods": ["PUT", "POST"],
     "url": {
       "paths": ["{index}/_mapping"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_settings.json

@@ -1,6 +1,7 @@
 {
   "indices.put_settings": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-update-settings.html",
+    "stability": "stable",
     "methods": ["PUT"],
     "url": {
       "paths": ["/_settings", "/{index}/_settings"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.put_template.json

@@ -1,6 +1,7 @@
 {
   "indices.put_template": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-templates.html",
+    "stability": "stable",
     "methods": ["PUT", "POST"],
     "url": {
       "paths": ["/_template/{name}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.recovery.json

@@ -1,6 +1,7 @@
 {
     "indices.recovery" : {
         "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-recovery.html",
+        "stability": "stable",
         "methods": ["GET"],
         "url": {
             "paths": ["/_recovery", "/{index}/_recovery"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.refresh.json

@@ -1,6 +1,7 @@
 {
   "indices.refresh": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-refresh.html",
+    "stability": "stable",
     "methods": ["POST", "GET"],
     "url": {
       "paths": ["/_refresh", "/{index}/_refresh"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.rollover.json

@@ -1,6 +1,7 @@
 {
   "indices.rollover": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-rollover-index.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/{alias}/_rollover", "/{alias}/_rollover/{new_index}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.segments.json

@@ -1,6 +1,7 @@
 {
   "indices.segments": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-segments.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_segments", "/{index}/_segments"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.shard_stores.json

@@ -1,6 +1,7 @@
 {
   "indices.shard_stores": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-shards-stores.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_shard_stores", "/{index}/_shard_stores"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.shrink.json

@@ -1,6 +1,7 @@
 {
   "indices.shrink": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-shrink-index.html",
+    "stability": "stable",
     "methods": ["PUT", "POST"],
     "url": {
       "paths": ["/{index}/_shrink/{target}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.split.json

@@ -1,6 +1,7 @@
 {
   "indices.split": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-split-index.html",
+    "stability": "stable",
     "methods": ["PUT", "POST"],
     "url": {
       "paths": ["/{index}/_split/{target}"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.stats.json

@@ -1,6 +1,7 @@
 {
   "indices.stats": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-stats.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": [

rest-api-spec/src/main/resources/rest-api-spec/api/indices.update_aliases.json

@@ -1,6 +1,7 @@
 {
   "indices.update_aliases": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-aliases.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/_aliases"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.upgrade.json

@@ -1,6 +1,7 @@
 {
   "indices.upgrade": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-upgrade.html",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/_upgrade", "/{index}/_upgrade"],

rest-api-spec/src/main/resources/rest-api-spec/api/indices.validate_query.json

@@ -1,6 +1,7 @@
 {
   "indices.validate_query": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/search-validate.html",
+    "stability": "stable",
     "methods": ["GET", "POST"],
     "url": {
       "paths": ["/_validate/query", "/{index}/_validate/query"],

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

@@ -1,6 +1,7 @@
 {
   "info": {
     "documentation": "http://www.elastic.co/guide/",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/"],

rest-api-spec/src/main/resources/rest-api-spec/api/ingest.delete_pipeline.json

@@ -1,6 +1,7 @@
 {
   "ingest.delete_pipeline": {
     "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/master/delete-pipeline-api.html",
+    "stability": "stable",
     "methods": [ "DELETE" ],
     "url": {
       "paths": [ "/_ingest/pipeline/{id}" ],

rest-api-spec/src/main/resources/rest-api-spec/api/ingest.get_pipeline.json

@@ -1,6 +1,7 @@
 {
   "ingest.get_pipeline": {
     "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/master/get-pipeline-api.html",
+    "stability": "stable",
     "methods": [ "GET" ],
     "url": {
       "paths": [ "/_ingest/pipeline", "/_ingest/pipeline/{id}" ],

rest-api-spec/src/main/resources/rest-api-spec/api/ingest.processor_grok.json

@@ -1,6 +1,7 @@
 {
   "ingest.processor_grok": {
     "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/master/grok-processor.html#grok-processor-rest-get",
+    "stability": "stable",
     "methods": [ "GET" ],
     "url": {
       "paths": ["/_ingest/processor/grok"],

rest-api-spec/src/main/resources/rest-api-spec/api/ingest.put_pipeline.json

@@ -1,6 +1,7 @@
 {
   "ingest.put_pipeline": {
     "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/master/put-pipeline-api.html",
+    "stability": "stable",
     "methods": [ "PUT" ],
     "url": {
       "paths": [ "/_ingest/pipeline/{id}" ],

rest-api-spec/src/main/resources/rest-api-spec/api/ingest.simulate.json

@@ -1,6 +1,7 @@
 {
   "ingest.simulate": {
     "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/master/simulate-pipeline-api.html",
+    "stability": "stable",
     "methods": [ "GET", "POST" ],
     "url": {
       "paths": [ "/_ingest/pipeline/_simulate", "/_ingest/pipeline/{id}/_simulate" ],

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

@@ -1,6 +1,7 @@
 {
   "mget": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-multi-get.html",
+    "stability": "stable",
     "methods": ["GET", "POST"],
     "url": {
       "paths": ["/_mget", "/{index}/_mget"],

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

@@ -1,6 +1,7 @@
 {
   "msearch": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/search-multi-search.html",
+    "stability": "stable",
     "methods": ["GET", "POST"],
     "url": {
       "paths": ["/_msearch", "/{index}/_msearch"],

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

@@ -1,6 +1,7 @@
 {
   "msearch_template": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html",
+    "stability": "stable",
     "methods": ["GET", "POST"],
     "url": {
       "paths": ["/_msearch/template", "/{index}/_msearch/template"],

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

@@ -1,6 +1,7 @@
 {
   "mtermvectors" : {
     "documentation" : "http://www.elastic.co/guide/en/elasticsearch/reference/master/docs-multi-termvectors.html",
+    "stability": "stable",
     "methods" : ["GET", "POST"],
     "url" : {
       "paths" : ["/_mtermvectors", "/{index}/_mtermvectors"],

rest-api-spec/src/main/resources/rest-api-spec/api/nodes.hot_threads.json

@@ -1,6 +1,7 @@
 {
   "nodes.hot_threads": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-nodes-hot-threads.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_nodes/hot_threads",  "/_nodes/{node_id}/hot_threads"],

rest-api-spec/src/main/resources/rest-api-spec/api/nodes.info.json

@@ -1,6 +1,7 @@
 {
   "nodes.info": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-nodes-info.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": ["/_nodes", "/_nodes/{node_id}", "/_nodes/{metric}", "/_nodes/{node_id}/{metric}"],

rest-api-spec/src/main/resources/rest-api-spec/api/nodes.reload_secure_settings.json

@@ -1,6 +1,7 @@
 {
   "nodes.reload_secure_settings": {
     "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/master/secure-settings.html#reloadable-secure-settings",
+    "stability": "stable",
     "methods": ["POST"],
     "url": {
       "paths": ["/_nodes/reload_secure_settings", "/_nodes/{node_id}/reload_secure_settings"],

rest-api-spec/src/main/resources/rest-api-spec/api/nodes.stats.json

@@ -1,6 +1,7 @@
 {
   "nodes.stats": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-nodes-stats.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": [

rest-api-spec/src/main/resources/rest-api-spec/api/nodes.usage.json

@@ -1,6 +1,7 @@
 {
   "nodes.usage": {
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-nodes-usage.html",
+    "stability": "stable",
     "methods": ["GET"],
     "url": {
       "paths": [