Documents the new deprecations options on the rest-api-spec (#41444) (#…

…43090)

* Documents the new deprecations options on the rest-api-spec

Relates #41439 #38613 #35262

* remove reference to path now that #41452 is merged, also fixed missing a comma rendering the example json invalid

* removed one more instance of path

* make sure json examples are self contained and not excerpts

(cherry picked from commit 4430f99)

rest-api-spec/README.markdown

@@ -12,7 +12,6 @@ Example for the ["Create Index"](http://www.elastic.co/guide/en/elasticsearch/re
     "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-create-index.html",
     "methods": ["PUT", "POST"],
     "url": {
-      "path": "/{index}",
       "paths": ["/{index}"],
       "parts": {
         "index": {
@@ -46,6 +45,78 @@ The specification contains:
 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.
 
+## Backwards compatibility 
+
+The specification follows the same backward compatibility guarantees as Elasticsearch. 
+
+- Within a Major, additions only. 
+  - If an item has been documented wrong it should be deprecated instead as removing these might break downstream clients.
+- Major version change, may deprecate pieces or simply remove them given enough deprecation time.
+
+## Deprecations
+
+The spec allows for deprecations of:
+
+#### Entire API:
+
+```json
+{
+  "api" : {
+    "documentation": "...",
+    "deprecated" : {
+      "version" : "7.0.0",
+      "description" : "Reason API is being deprecated"
+    },
+  }
+}
+```
+
+#### Specific paths:
+
+```json
+{
+  "api": {
+    "documentation": "",
+    "url": {
+      "paths": ["/_monitoring/bulk"],
+      "deprecated_paths" : [
+        {
+          "version" : "7.0.0",
+          "path" : "/_monitoring/{type}/bulk",
+          "description" : "Specifying types in urls has been deprecated"
+        }
+      ]
+    }
+  }
+}
+```
+
+Here `paths` describes the preferred paths and `deprecated_paths` indicates `paths` that will still work but are now 
+deprecated.
+
+#### Parameters 
+
+```json
+{
+  "api": {
+    "documentation": "",
+    "methods": ["GET"],
+    "url": {
+      "params": {
+        "stored_fields": {
+          "type": "list",
+          "description" : "",
+          "deprecated" : {
+            "version" : "7.0.0",
+            "description" : "Reason parameter is being deprecated"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## License
 
 This software is licensed under the Apache License, version 2 ("ALv2").