From 26cdef80a4787b05328a7bce421393430bb4280d Mon Sep 17 00:00:00 2001
From: Mpdreamz <Mpdreamz@gmail.com>
Date: Tue, 23 Apr 2019 15:09:48 +0200
Subject: [PATCH 1/4] Documents the new deprecations options on the
 rest-api-spec

Relates #41439 #38613 #35262
---
 rest-api-spec/README.markdown | 66 +++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/rest-api-spec/README.markdown b/rest-api-spec/README.markdown
index 56b5e9b553b83..b50c00d0a0348 100644
--- a/rest-api-spec/README.markdown
+++ b/rest-api-spec/README.markdown
@@ -46,6 +46,72 @@ 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": {
+      "path": "/_monitoring/bulk",
+      "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 prefered 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").

From 92f8255feec57e324b6cb91e54e8b795a413397f Mon Sep 17 00:00:00 2001
From: Mpdreamz <Mpdreamz@gmail.com>
Date: Tue, 11 Jun 2019 11:30:52 +0200
Subject: [PATCH 2/4] remove reference to path now that #41452 is merged, also
 fixed missing a comma rendering the example json invalid

---
 rest-api-spec/README.markdown | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/rest-api-spec/README.markdown b/rest-api-spec/README.markdown
index b50c00d0a0348..ca3ad4c8a56a9 100644
--- a/rest-api-spec/README.markdown
+++ b/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": {
@@ -90,7 +89,7 @@ The spec allows for deprecations of:
       ],
 ```
 
-Here `paths` describes the prefered paths and `deprecated_paths` indicates `paths` that will still work but are now 
+Here `paths` describes the preferred paths and `deprecated_paths` indicates `paths` that will still work but are now 
 deprecated.
 
 #### Parameters 
@@ -104,11 +103,11 @@ deprecated.
       "params": {
         "stored_fields": {
           "type": "list",
-          "description" : ""
-            "deprecated" : {
-              "version" : "7.0.0",
-              "description" : "Reason parameter is being deprecated"
-            },
+          "description" : "",
+          "deprecated" : {
+            "version" : "7.0.0",
+            "description" : "Reason parameter is being deprecated"
+          },
         },
 ```
 

From e54bb38c0dbcf2b0543951d8f5c44599616cb2be Mon Sep 17 00:00:00 2001
From: Mpdreamz <Mpdreamz@gmail.com>
Date: Tue, 11 Jun 2019 11:34:34 +0200
Subject: [PATCH 3/4] removed one more instance of path

---
 rest-api-spec/README.markdown | 1 -
 1 file changed, 1 deletion(-)

diff --git a/rest-api-spec/README.markdown b/rest-api-spec/README.markdown
index ca3ad4c8a56a9..f46a9aca62c1f 100644
--- a/rest-api-spec/README.markdown
+++ b/rest-api-spec/README.markdown
@@ -78,7 +78,6 @@ The spec allows for deprecations of:
   "api": {
     "documentation": "",
     "url": {
-      "path": "/_monitoring/bulk",
       "paths": ["/_monitoring/bulk"],
       "deprecated_paths" : [
         {

From 5be66f3eaf57f177efc2b66d60167ce7991bd10d Mon Sep 17 00:00:00 2001
From: Mpdreamz <Mpdreamz@gmail.com>
Date: Tue, 11 Jun 2019 11:37:23 +0200
Subject: [PATCH 4/4] make sure json examples are self contained and not
 excerpts

---
 rest-api-spec/README.markdown | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/rest-api-spec/README.markdown b/rest-api-spec/README.markdown
index f46a9aca62c1f..d6c7889f38030 100644
--- a/rest-api-spec/README.markdown
+++ b/rest-api-spec/README.markdown
@@ -85,7 +85,10 @@ The spec allows for deprecations of:
           "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 
@@ -106,8 +109,12 @@ deprecated.
           "deprecated" : {
             "version" : "7.0.0",
             "description" : "Reason parameter is being deprecated"
-          },
-        },
+          }
+        }
+      }
+    }
+  }
+}
 ```
 
 ## License