[DOCS] Adds information about version compatibility headers (elastic#…

…77096) * [DOCS] Adds information about version compatibility * Clarified that the behavior is not guaranteed to be the same * Update docs/reference/api-conventions.asciidoc * Update docs/reference/api-conventions.asciidoc * Update docs/reference/api-conventions.asciidoc Co-authored-by: Adam Locke <adam.locke@elastic.co> Co-authored-by: Adam Locke <adam.locke@elastic.co>
debadair · Sep 3, 2021 · 9cd8cfd · 9cd8cfd
1 parent 783afbc
commit 9cd8cfd
Showing 1 changed file with 31 additions and 0 deletions.
diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc
@@ -11,6 +11,37 @@ Alternatively, you can pass the request body as the
 <<api-request-body-query-string, `source` query string parameter>>
 when using GET.
 
+[discrete]
+[[api-compatibility]]
+=== REST API version compatibility
+
+Major version upgrades often include a number of breaking changes 
+that impact how you interact with {es}. 
+While we recommend that you monitor the deprecation logs and 
+update applications before upgrading {es},
+having to coordinate the necessary changes can be an impediment to upgrading. 
+
+You can enable an existing application to function without modification after
+an upgrade by including API compatibility headers, which tell {es} you are still
+using the previous version of the REST API. Using these headers allows the 
+structure of requests and responses to remain the same; it does not guarantee
+the same behavior. 
+
+
+You set version compatibility on a per-request basis in the `Content-Type` and `Accept` headers. 
+Setting `compatible-with` to the same major version as 
+the version you're running has no impact, 
+but ensures that the request will still work after {es} is upgraded. 
+
+To tell {es} 8.0 you are using the 7.x request and response format, 
+set `compatible-with=7`:
+
+[source,sh]
+----------------------------------------------------------------------
+Content-Type: application/vnd.elasticsearch+json; compatible-with=7
+Accept: application/vnd.elasticsearch+json; compatible-with=7
+----------------------------------------------------------------------
+
 * <<multi-index>>
 * <<date-math-index-names>>
 * <<cron-expressions>>