From 606f83838a3343208b1cc45f211126c5471f5e5d Mon Sep 17 00:00:00 2001 From: Deb Adair Date: Tue, 31 Aug 2021 17:06:25 -0700 Subject: [PATCH 1/5] [DOCS] Adds information about version compatibility --- docs/reference/api-conventions.asciidoc | 28 +++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index 304181792cb4f..e45a71e6b264a 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -214,6 +214,34 @@ instead. When using this method, the `source_content_type` parameter should also be passed with a media type value that indicates the format of the source, such as `application/json`. +[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 log and +update applications before upgrading {es}, +having to coordinate the necessary changes can be an impediment to upgrading. + +To enable an application to continue to function without modification after an upgrade, +you can include API compatibility headers that tell {es} that +you are still using the previous version of the REST API. +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 +---------------------------------------------------------------------- + [discrete] [[api-url-access-control]] === URL-based access control From 9061c0388ae24937ffee9a8e3c8ddab3d38c3e97 Mon Sep 17 00:00:00 2001 From: Deb Adair Date: Wed, 1 Sep 2021 15:08:24 -0700 Subject: [PATCH 2/5] Clarified that the behavior is not guaranteed to be the same --- docs/reference/api-conventions.asciidoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index e45a71e6b264a..1e28f1369be47 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -227,8 +227,11 @@ having to coordinate the necessary changes can be an impediment to upgrading. To enable an application to continue to function without modification after an upgrade, you can include API compatibility headers that tell {es} that you are still using the previous version of the REST API. -You set version compatibility on a per-request basis in the `Content-Type` and `Accept` headers. +Using the 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. From 6a84576afc246b1e3d9358b08bd296a4098d9c71 Mon Sep 17 00:00:00 2001 From: debadair Date: Thu, 2 Sep 2021 14:06:28 -0700 Subject: [PATCH 3/5] Update docs/reference/api-conventions.asciidoc --- docs/reference/api-conventions.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index 1e28f1369be47..2fa319b01cfe5 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -227,7 +227,7 @@ having to coordinate the necessary changes can be an impediment to upgrading. To enable an application to continue to function without modification after an upgrade, you can include API compatibility headers that tell {es} that you are still using the previous version of the REST API. -Using the headers allows the structure of requests and responses to remain the same, +Using the headers allows the structure of requests and responses to remain the same; it does not guarantee the same behavior. From f0436bd98a093ef7c437204c0cc3e606bdd72178 Mon Sep 17 00:00:00 2001 From: debadair Date: Fri, 3 Sep 2021 14:13:14 -0700 Subject: [PATCH 4/5] Update docs/reference/api-conventions.asciidoc --- docs/reference/api-conventions.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index 2fa319b01cfe5..20ffb08715151 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -220,7 +220,7 @@ of the source, such as `application/json`. 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 log and +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. From 6e80419bca6eef965cdf63eeda70a617d7ab3402 Mon Sep 17 00:00:00 2001 From: debadair Date: Fri, 3 Sep 2021 14:16:30 -0700 Subject: [PATCH 5/5] Update docs/reference/api-conventions.asciidoc Co-authored-by: Adam Locke --- docs/reference/api-conventions.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index 20ffb08715151..71b60f9e3d402 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -224,11 +224,11 @@ 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. -To enable an application to continue to function without modification after an upgrade, -you can include API compatibility headers that tell {es} that -you are still using the previous version of the REST API. -Using the headers allows the structure of requests and responses to remain the same; -it does not guarantee the same behavior. +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.