From feac71c47d5e9fd4e00bc2d3cfee179798b3a65a Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Thu, 3 Feb 2022 16:28:39 -0600 Subject: [PATCH 01/30] initial stab at compat api docs --- .../migrate_8_0/rest-api-changes.asciidoc | 59 +++++++++++++++ docs/reference/rest-api/index.asciidoc | 2 + .../rest-api/rest-api-compatibility.asciidoc | 72 +++++++++++++++++++ docs/reference/upgrade.asciidoc | 18 +++-- 4 files changed, 146 insertions(+), 5 deletions(-) create mode 100644 docs/reference/rest-api/rest-api-compatibility.asciidoc diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index 11eefa04d3429..a6d583c0bc009 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -18,6 +18,11 @@ is replaced with a new endpoint that does not contain `_xpack`. As an example, *Impact* + Use the replacement REST API endpoints. Requests submitted to the `_xpack` API endpoints will return an error. + +*Compatibility* + +When <> is <> +any requests that include the`_xpack` prefix will be rerouted to the corresponding +URL without the `_xpack` prefix. ==== [[remove-mapping-type-api-endpoints]] @@ -161,6 +166,14 @@ also been removed. Use a typeless endpoint instead. *Impact* + Update your application to use typeless REST API endpoints. Requests to endpoints that contain a mapping type will return an error. + +*Compatibility* + +When <> is <> +any requests that include the custom mapping types, the custom mapping type will +be ignored. URLs will be rerouted to the corresponding URL without the a mapping type. +Custom mapping types in request bodies will be ignored, type related HTTP +parameters will be ignored and responses, where warranted, will include `_type` : `_doc`. + ==== .{ccs-cap} ({ccs-init}) is now only backward-compatible with the previous minor version. @@ -214,6 +227,10 @@ sort buckets by their term, use `_key` instead. *Impact* + Discontinue use of the `_term` order key. Requests that include a `_term` order key will return an error. + +*Compatibility* + +When <> is <> +the `_term` order is ignored and `key` is used instead ==== [[remove-time-order-key]] @@ -227,6 +244,10 @@ values. To sort buckets by their key, use `_key` instead. *Impact* + Discontinue use of the `_time` order key. Requests that include a `_time` order key will return an error. + +*Compatibility* + +When <> is <> +the `_time` order is ignored and `_key` is used instead. ==== [[remove-moving-avg-agg]] @@ -242,6 +263,8 @@ aggregation] instead. *Impact* + Discontinue use of the `moving_avg` aggregation. Requests that include the `moving_avg` aggregation will return an error. + + ==== [[percentile-duplication]] @@ -257,6 +280,7 @@ its values must be unique. Otherwise, an exception occurs. Use unique values in the `percents` parameter of the `percentiles` aggregation. Requests containing duplicate values in the `percents` parameter will return an error. + ==== [[date-histogram-interval]] @@ -276,6 +300,12 @@ Uses of the `interval` parameter in either the `date_histogram` aggregation or the `date_histogram` composite source will now generate an error. Instead please use the more specific `fixed_interval` or `calendar_interval` parameters. + + +*Compatibility* + +When <> is <> +the `interval` parameter will be adapted to the either a fixed or calendar interval. + ==== [[ngram-edgengram-filter-names-removed]] @@ -436,6 +466,11 @@ parameter is now removed in 8.0. Use the {ref}/indices-templates-v1.html[create or update index template API]'s `index_patterns` parameter. Requests that include the `template` parameter will return an error. + +*Compatibility* + +When <> is <> +the `template` parameter mapped to `index_patterns`. + ==== .Synced flush has been removed. @@ -448,6 +483,10 @@ instead as it has the same effect as a synced flush in 7.6 and later. *Impact* + Use the {ref}/indices-flush.html[flush API]. Requests to the `//flush/synced` or `/flush/synced` endpoints will return an error. + +*Compatibility* + +When <> is <> +the request to synced flush will be routed to the equivalent non-synced flush URL. ==== .The default for the `?wait_for_active_shards` parameter on the close index API has changed. @@ -477,6 +516,10 @@ stats for specific mapping types. Mapping types have been removed in 8.0. *Impact* + Discontinue use of the `types` query parameter. Requests that include the parameter will return an error. + +*Compatibility* + +When <> is <> +the `types` query parameter is ignored returning the stats for the entire index. ==== .The `user_agent` ingest processor's `ecs` parameter has no effect. @@ -504,6 +547,11 @@ include a mapping type name. Mapping types have been removed in 8.x. *Impact* + Discontinue use of the `include_type_name` query parameter. Requests that include the parameter will return an error. + +*Compatibility* + +When <> is <> +the `include_type_name` query parameter is ignored and any custom mapping types +in the request will be removed. ==== .Reindex from remote now re-encodes URL-encoded index names. @@ -537,6 +585,11 @@ Similarly, the `size` parameter has been renamed to `max_docs` for *Impact* + Use the replacement parameters. Requests containing the `size` parameter will return an error. + +*Compatibility* + +When <> is <> +the `size` parameter will be mapped to the `max_docs` parameter. + ==== .The update by query API now rejects unsupported `script` fields. @@ -875,6 +928,11 @@ removed in 8.0. *Impact* + Discontinue use of the `use_field_mapping` request body parameter. Requests containing this parameter will return an error. + +*Compatibility* + +When <> is <> +the `use_field_mapping` is ignored. + ==== .The search API's `from` request body and url parameter cannot be negative. @@ -929,6 +987,7 @@ The `type` query has been removed. Mapping types have been removed in 8.0. *Impact* + Discontinue use of the `type` query. Requests that include the `type` query will return an error. + ==== .The `kibana_user` role has been renamed `kibana_admin`. diff --git a/docs/reference/rest-api/index.asciidoc b/docs/reference/rest-api/index.asciidoc index 1a8569b42d3b2..532b814ad5619 100644 --- a/docs/reference/rest-api/index.asciidoc +++ b/docs/reference/rest-api/index.asciidoc @@ -12,6 +12,7 @@ not be included yet. * <> * <> +* <> * <> * <> * <> @@ -52,6 +53,7 @@ not be included yet. include::{es-repo-dir}/api-conventions.asciidoc[] include::{es-repo-dir}/rest-api/common-options.asciidoc[] +include::{es-repo-dir}/rest-api/rest-api-compatibility.asciidoc[] include::{es-repo-dir}/autoscaling/apis/autoscaling-apis.asciidoc[] include::{es-repo-dir}/cat.asciidoc[] include::{es-repo-dir}/cluster.asciidoc[] diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc new file mode 100644 index 0000000000000..0e3468ca6ca09 --- /dev/null +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -0,0 +1,72 @@ +[[rest-api-compatibility]] +== REST API compatibility + +REST API compatibility in a per-request opt-in feature that can help REST clients mitigate non compatible (breaking) changes to the REST API. + +{es} REST API's are generally stable across major versions. However, there are cases where {es} REST API's are changed in a non compatible ways (breaking) with the prior major version. +For example, {es} 7.x supported custom mapping types in many of the URL paths, but {es} 8.0+ does not support +custom mapping types (see <>). As a result a REST client that is still using custom types in the +URL paths to communicating with {es} 8.0+ will error. If requested, REST API compatibility can allow that request to succeed even though mapping types are no longer supported. + +All non compatible (breaking) changes to the {es} REST API will be deprecated in the prior major version to where the non compatible (breaking) change occurs. +For example, if a REST API is removed (or changed in some non compatible way) in 8.x it will be will be deprecated in 7.x and will emit deprecation logs anytime that API is invoked. +This provides the opportunity to review the deprecation logs prior to a major version upgrade and take the appropriate actions. However, there are cases where +identifying all usages of deprecated APIs could be difficult or impossible. This is where REST API compatibility can help. + +When requested, REST API compatibility instructs the {es} server to attempt to honor the REST API of the prior major version. +For most API's REST API compatibility has no effect. Requests for compatibility only impacts APIs that have non compatible (breaking) changes from the prior major version. +For example, custom mapping types were supported in URL paths for 7.x, but are not supported in 8.x. When compatibility is requested {es} will internally and automatically redirect any URL that +includes the custom mapping type to it's non-typed equivalent URL. In this case, requesting compatibility effectively ignores the custom mapping type of the requested URL. +Additionally, for requests that would have warranted a response that in 7.x that included a type field REST API compatibility will inject a _type field with a hard coded value of _doc as part of the response. + +REST API compatibility is not constrained only to the removal of mappings types. REST API compatibility can be requested for any API and the {es} will attempt to apply the most compatible +URL, request body, response body, and HTTP parameters. If the API does not have non compatible (breaking) changes then it is no different than a normal request. +Additionally, there may be some cases where compatibility can not be automatically applied. For those cases an error will still occur. + +It is important to note that REST API compatibility does not result in the same behavior as the prior version. Rather REST API compatibility is a best effort by the {es} service to find the best way to automatically resolve any incompatibility introduced in the REST API. +This level of compatibility may not work for all workflows and use cases. For example, if the custom mapping types are an integral part of a workflow then ignoring the custom type at the REST API will not help. + +Any time REST API compatibility is requested and is invoked due to a non compatible (breaking) change, an entry to the deprecation log with the category "compatible_api" is recorded. This can be used to help identify any gaps in usage and fully supported features. +REST API compatibility should be a bridge help smooth out a major version upgrade, not a long term strategy. REST API compatibility is only honored across one major version (i.e. honor 7.x requests/response from 8.x). + +Review the release notes for REST API changes for additional details. TODO: link to https://www.elastic.co/guide/en/elasticsearch/reference/master/migrating-8.0.html#breaking_80_rest_api_changes + +[discrete] +[[request-rest-api-compatibility]] +=== Requesting REST API compatibility + +REST API compatibility is implemented per request via the Accept and/or Content-Type headers. + +For example: + +[source] +------------------------------------------------------------ +Accept: "application/vnd.elasticsearch+json;compatible-with=7" +Content-Type: "application/vnd.elasticsearch+json;compatible-with=7" +------------------------------------------------------------ + +The Accept header is always required and the Content-Type header is only required when a body is sent with the request. +The following values are valid when communicating with a 7.x or 8.x {es} server: +[source] +------------------------------------------------------------ +"application/vnd.elasticsearch+json;compatible-with=7" +"application/vnd.elasticsearch+yaml;compatible-with=7" +"application/vnd.elasticsearch+smile;compatible-with=7" +"application/vnd.elasticsearch+cbor;compatible-with=7" +------------------------------------------------------------ + +The link:/guide[officially supported Elasticsearch clients] can enable REST API compatibility for all requests. TODO: link to https://www.elastic.co/guide/en/elasticsearch/client/index.html +To enable REST API compatibility for all requests set the environment variable `ELASTIC_CLIENT_APIVERSIONING` to true. + +[discrete] +=== REST API compatibility workflow + +The recommended workflow for upgrading to a new major and leverage REST API compatibility is as follows (from 7.x to 8.x): + +1. Upgrade any officially supported Elasticsearch clients to the latest 7.x version and enable REST API compatibility. TODO: link to https://www.elastic.co/guide/en/elasticsearch/client/index.html +2. Use the {kibana-ref}/upgrade-assistant.html[Kibana upgrade assistant] and review all critical issues. Some critical issues may be mitigated by REST API compatibility. +3. From the {kibana-ref}/upgrade-assistant.html[Kibana upgrade assistant] explore the deprecation logs and resolve all critical issues +4. Upgrade Elasticsearch to 8.x +5. Review the deprecation logs. If compatibility is invoked it will be logged to the deprecation logs with the category "compatible_api". Review the workflow associated with any invoked compatibility. +6. Upgrade the official {es} clients to the matching 8.x version resolving any cases where compatibility needs to be manually resolved. + diff --git a/docs/reference/upgrade.asciidoc b/docs/reference/upgrade.asciidoc index 68ad344328f49..75071c3d4ca52 100644 --- a/docs/reference/upgrade.asciidoc +++ b/docs/reference/upgrade.asciidoc @@ -5,12 +5,12 @@ -- ifeval::["{release-state}"!="released"] [[upgrade-pre-release]] -IMPORTANT: This documentation is for a pre-release of {es} {minor-version}. +IMPORTANT: This documentation is for a pre-release of {es} {minor-version}. Upgrades from pre-release builds are not supported and -could result in errors or data loss. -If you upgrade from a released version to a pre-release verion for testing, +could result in errors or data loss. +If you upgrade from a released version to a pre-release verion for testing, discard the contents of the cluster when you are done. -Do not attempt to upgrade to the final release. +Do not attempt to upgrade to the final release. endif::[] {es} can usually be upgraded using a <> @@ -44,7 +44,7 @@ other functionality that may have changed. [cols="<1,3",options="header",] |==== -|Upgrade from +|Upgrade from |Recommended upgrade path to {version} ifeval::[ "{bare_version}" != "{minor-version}.0" ] @@ -107,6 +107,14 @@ When upgrading to a new version of {es}, you need to upgrade each of the products in your Elastic Stack. For more information, see the {stack-ref}/upgrading-elastic-stack.html[Elastic Stack Installation and Upgrade Guide]. +[discrete] +[[upgrade-rest-api-compatibility]] +=== REST API compatibility + +REST API compatibility in a per-request opt-in feature that can help REST clients +mitigate non compatible (breaking) changes to the REST API. +See <> for additional information. + [discrete] [[upgrade-fips-java17]] === FIPS Compliance and Java 17 From be39b5131118401f7655541ca3e8808580c9729a Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Thu, 3 Feb 2022 16:47:50 -0600 Subject: [PATCH 02/30] fix build error --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index 0e3468ca6ca09..a00f4702e76b8 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -39,7 +39,7 @@ REST API compatibility is implemented per request via the Accept and/or Content- For example: -[source] +[source, text] ------------------------------------------------------------ Accept: "application/vnd.elasticsearch+json;compatible-with=7" Content-Type: "application/vnd.elasticsearch+json;compatible-with=7" @@ -47,7 +47,7 @@ Content-Type: "application/vnd.elasticsearch+json;compatible-with=7" The Accept header is always required and the Content-Type header is only required when a body is sent with the request. The following values are valid when communicating with a 7.x or 8.x {es} server: -[source] +[source, text] ------------------------------------------------------------ "application/vnd.elasticsearch+json;compatible-with=7" "application/vnd.elasticsearch+yaml;compatible-with=7" From 0a47ad36860f4678471a2d0c3324c6e9d31263e7 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:17:29 -0600 Subject: [PATCH 03/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index a6d583c0bc009..4e4c0eb60d94d 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -21,7 +21,7 @@ API endpoints will return an error. *Compatibility* + When <> is <> -any requests that include the`_xpack` prefix will be rerouted to the corresponding +any requests that include the`_xpack` prefix are rerouted to the corresponding URL without the `_xpack` prefix. ==== From 08423a43b1e7d0400a52b06ed2706f57527525f3 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:17:36 -0600 Subject: [PATCH 04/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index 4e4c0eb60d94d..cca67ed583e18 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -20,7 +20,7 @@ Use the replacement REST API endpoints. Requests submitted to the `_xpack` API endpoints will return an error. *Compatibility* + -When <> is <> +When <> is <>, any requests that include the`_xpack` prefix are rerouted to the corresponding URL without the `_xpack` prefix. ==== From f77fed395740eb183710f83ed03e31d411def3ca Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:18:13 -0600 Subject: [PATCH 05/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- .../migration/migrate_8_0/rest-api-changes.asciidoc | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index cca67ed583e18..9839d09d8d2fc 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -168,11 +168,9 @@ Update your application to use typeless REST API endpoints. Requests to endpoints that contain a mapping type will return an error. *Compatibility* + -When <> is <> -any requests that include the custom mapping types, the custom mapping type will -be ignored. URLs will be rerouted to the corresponding URL without the a mapping type. -Custom mapping types in request bodies will be ignored, type related HTTP -parameters will be ignored and responses, where warranted, will include `_type` : `_doc`. +When <> is <>, if a request includes a custom mapping type it is ignored. The request is rerouted to the corresponding typeless URL. +Custom mapping types in request bodies and type related HTTP +parameters are ignored, and responses, where warranted, include `_type` : `_doc`. ==== From db7b284432f42bdcf980c4886c8f4f079953490c Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:18:22 -0600 Subject: [PATCH 06/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- .../reference/migration/migrate_8_0/rest-api-changes.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index 9839d09d8d2fc..c583f73bf5c89 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -227,8 +227,8 @@ Discontinue use of the `_term` order key. Requests that include a `_term` order key will return an error. *Compatibility* + -When <> is <> -the `_term` order is ignored and `key` is used instead +When <> is <>, +the `_term` order is ignored and `key` is used instead. ==== [[remove-time-order-key]] From a02b6b0a4d779325ab7f43b96dcf53b9b17e1f88 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:18:35 -0600 Subject: [PATCH 07/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index c583f73bf5c89..1a4d8624101d4 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -244,7 +244,7 @@ Discontinue use of the `_time` order key. Requests that include a `_time` order key will return an error. *Compatibility* + -When <> is <> +When <> is <>, the `_time` order is ignored and `_key` is used instead. ==== From cdc889fe9566e6acb9709fe93a131816a225369f Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:18:53 -0600 Subject: [PATCH 08/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index a00f4702e76b8..db57542bedf47 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -26,8 +26,8 @@ Additionally, there may be some cases where compatibility can not be automatical It is important to note that REST API compatibility does not result in the same behavior as the prior version. Rather REST API compatibility is a best effort by the {es} service to find the best way to automatically resolve any incompatibility introduced in the REST API. This level of compatibility may not work for all workflows and use cases. For example, if the custom mapping types are an integral part of a workflow then ignoring the custom type at the REST API will not help. -Any time REST API compatibility is requested and is invoked due to a non compatible (breaking) change, an entry to the deprecation log with the category "compatible_api" is recorded. This can be used to help identify any gaps in usage and fully supported features. -REST API compatibility should be a bridge help smooth out a major version upgrade, not a long term strategy. REST API compatibility is only honored across one major version (i.e. honor 7.x requests/response from 8.x). +When you submit requests using REST API compatibility and {es} resolves the incompatibility, a message is written to the deprecation log with the category "compatible_api". Review the deprecation log to identify any gaps in usage and fully supported features. + Review the release notes for REST API changes for additional details. TODO: link to https://www.elastic.co/guide/en/elasticsearch/reference/master/migrating-8.0.html#breaking_80_rest_api_changes From 103365631f18fa63864eee9a198179131e8d3f27 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:19:09 -0600 Subject: [PATCH 09/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- .../migration/migrate_8_0/rest-api-changes.asciidoc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index 1a4d8624101d4..dbe8ccf19d6e3 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -299,11 +299,9 @@ the `date_histogram` composite source will now generate an error. Instead please use the more specific `fixed_interval` or `calendar_interval` parameters. - *Compatibility* + -When <> is <> -the `interval` parameter will be adapted to the either a fixed or calendar interval. - +When <> is <>, +the `interval` parameter is adapted to either a fixed or calendar interval. ==== [[ngram-edgengram-filter-names-removed]] From 90bb1cbc173c4044ea4c04c74634386cbe042290 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:19:22 -0600 Subject: [PATCH 10/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- .../reference/migration/migrate_8_0/rest-api-changes.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index dbe8ccf19d6e3..f421ded9d3ac9 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -464,8 +464,8 @@ Use the {ref}/indices-templates-v1.html[create or update index template API]'s return an error. *Compatibility* + -When <> is <> -the `template` parameter mapped to `index_patterns`. +When <> is <>, +the `template` parameter is mapped to `index_patterns`. ==== From b0fedbf0662d1f3d37bd9fd58b58c60ed1630867 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:19:56 -0600 Subject: [PATCH 11/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- .../rest-api/rest-api-compatibility.asciidoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index db57542bedf47..b35c1fbaed7cd 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -61,12 +61,12 @@ To enable REST API compatibility for all requests set the environment variable ` [discrete] === REST API compatibility workflow -The recommended workflow for upgrading to a new major and leverage REST API compatibility is as follows (from 7.x to 8.x): - -1. Upgrade any officially supported Elasticsearch clients to the latest 7.x version and enable REST API compatibility. TODO: link to https://www.elastic.co/guide/en/elasticsearch/client/index.html -2. Use the {kibana-ref}/upgrade-assistant.html[Kibana upgrade assistant] and review all critical issues. Some critical issues may be mitigated by REST API compatibility. -3. From the {kibana-ref}/upgrade-assistant.html[Kibana upgrade assistant] explore the deprecation logs and resolve all critical issues -4. Upgrade Elasticsearch to 8.x -5. Review the deprecation logs. If compatibility is invoked it will be logged to the deprecation logs with the category "compatible_api". Review the workflow associated with any invoked compatibility. -6. Upgrade the official {es} clients to the matching 8.x version resolving any cases where compatibility needs to be manually resolved. +To leverage REST API compatibility during an upgrade from 7.17 to {version}: + +1. Upgrade your https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} clients] to the latest 7.x version and enable REST API compatibility. +2. Use the {kibana-ref}/upgrade-assistant.html[Upgrade Assistant] to review all critical issues and explore the deprecation logs. Some critical issues might be mitigated by REST API compatibility. +3. Resolve all critical issues before proceeding with the upgrade. +4. Upgrade Elasticsearch to {version}. +5. Review the deprecation logs for entries with the category `compatible_api1`. Review the workflow associated with the requests that relied on compatibility mode. +6. Upgrade your {es} clients to 8.x and resolve compatibility issues manually where needed. From f2e0a98e114dc666e9b67850a851faa4b371d702 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:20:13 -0600 Subject: [PATCH 12/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index b35c1fbaed7cd..3291edbaf45db 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -29,7 +29,7 @@ This level of compatibility may not work for all workflows and use cases. For ex When you submit requests using REST API compatibility and {es} resolves the incompatibility, a message is written to the deprecation log with the category "compatible_api". Review the deprecation log to identify any gaps in usage and fully supported features. -Review the release notes for REST API changes for additional details. TODO: link to https://www.elastic.co/guide/en/elasticsearch/reference/master/migrating-8.0.html#breaking_80_rest_api_changes +For information about specific breaking changes and the impact of requesting compatibility mode, see <> in the migration guide. [discrete] [[request-rest-api-compatibility]] From fdd4e57d5ff8bf7f750199b21148e3aef345c631 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:20:27 -0600 Subject: [PATCH 13/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index 3291edbaf45db..2a3e6179c811e 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -54,9 +54,9 @@ The following values are valid when communicating with a 7.x or 8.x {es} server: "application/vnd.elasticsearch+smile;compatible-with=7" "application/vnd.elasticsearch+cbor;compatible-with=7" ------------------------------------------------------------ +The [link:/guide](https://www.elastic.co/guide/en/elasticsearch/client/index.html)[officially supported {es} clients] can enable REST API compatibility for all requests. -The link:/guide[officially supported Elasticsearch clients] can enable REST API compatibility for all requests. TODO: link to https://www.elastic.co/guide/en/elasticsearch/client/index.html -To enable REST API compatibility for all requests set the environment variable `ELASTIC_CLIENT_APIVERSIONING` to true. +To enable REST API compatibility for all requests received by {es} set the environment variable `ELASTIC_CLIENT_APIVERSIONING` to true. [discrete] === REST API compatibility workflow From e9591c839fc8255bf46abd2673d342e512c2ccdd Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:20:59 -0600 Subject: [PATCH 14/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- .../reference/migration/migrate_8_0/rest-api-changes.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index f421ded9d3ac9..6b09e20b7c11c 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -481,8 +481,8 @@ Use the {ref}/indices-flush.html[flush API]. Requests to the `//flush/synced` or `/flush/synced` endpoints will return an error. *Compatibility* + -When <> is <> -the request to synced flush will be routed to the equivalent non-synced flush URL. +When <> is <>, +the request to synced flush is routed to the equivalent non-synced flush URL. ==== .The default for the `?wait_for_active_shards` parameter on the close index API has changed. From f5df15051b6953e38813692b2f71f115d207c573 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:21:15 -0600 Subject: [PATCH 15/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- .../reference/migration/migrate_8_0/rest-api-changes.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index 6b09e20b7c11c..859c86d52c748 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -514,8 +514,8 @@ Discontinue use of the `types` query parameter. Requests that include the parameter will return an error. *Compatibility* + -When <> is <> -the `types` query parameter is ignored returning the stats for the entire index. +When <> is <>, +the `types` query parameter is ignored and stats are returned for the entire index. ==== .The `user_agent` ingest processor's `ecs` parameter has no effect. From 8cf35fb98ea8ba4d1f628b46b38d630220fcff1e Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:22:17 -0600 Subject: [PATCH 16/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index 2a3e6179c811e..a7c0e5051be62 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -19,9 +19,6 @@ For example, custom mapping types were supported in URL paths for 7.x, but are n includes the custom mapping type to it's non-typed equivalent URL. In this case, requesting compatibility effectively ignores the custom mapping type of the requested URL. Additionally, for requests that would have warranted a response that in 7.x that included a type field REST API compatibility will inject a _type field with a hard coded value of _doc as part of the response. -REST API compatibility is not constrained only to the removal of mappings types. REST API compatibility can be requested for any API and the {es} will attempt to apply the most compatible -URL, request body, response body, and HTTP parameters. If the API does not have non compatible (breaking) changes then it is no different than a normal request. -Additionally, there may be some cases where compatibility can not be automatically applied. For those cases an error will still occur. It is important to note that REST API compatibility does not result in the same behavior as the prior version. Rather REST API compatibility is a best effort by the {es} service to find the best way to automatically resolve any incompatibility introduced in the REST API. This level of compatibility may not work for all workflows and use cases. For example, if the custom mapping types are an integral part of a workflow then ignoring the custom type at the REST API will not help. From a39d97363cdf264a0c569a23c85aa21fac1924d2 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:22:28 -0600 Subject: [PATCH 17/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- .../reference/migration/migrate_8_0/rest-api-changes.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index 859c86d52c748..b15009be599b7 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -545,9 +545,9 @@ Discontinue use of the `include_type_name` query parameter. Requests that include the parameter will return an error. *Compatibility* + -When <> is <> +When <> is <>, the `include_type_name` query parameter is ignored and any custom mapping types -in the request will be removed. +in the request are removed. ==== .Reindex from remote now re-encodes URL-encoded index names. From 7f4cb6984d4c794866217e81c49d52a03fb770d5 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:22:39 -0600 Subject: [PATCH 18/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- .../reference/migration/migrate_8_0/rest-api-changes.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index b15009be599b7..1cb586aaca3ab 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -583,8 +583,8 @@ Use the replacement parameters. Requests containing the `size` parameter will return an error. *Compatibility* + -When <> is <> -the `size` parameter will be mapped to the `max_docs` parameter. +When <> is <>, +the `size` parameter is mapped to the `max_docs` parameter. ==== From 3b6b5cc7ba62fe65266c350919e7c403210589e5 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:22:50 -0600 Subject: [PATCH 19/30] Update docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc Co-authored-by: debadair --- .../reference/migration/migrate_8_0/rest-api-changes.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc index 1cb586aaca3ab..ca7031dd9b386 100644 --- a/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc +++ b/docs/reference/migration/migrate_8_0/rest-api-changes.asciidoc @@ -926,8 +926,8 @@ Discontinue use of the `use_field_mapping` request body parameter. Requests containing this parameter will return an error. *Compatibility* + -When <> is <> -the `use_field_mapping` is ignored. +When <> is <>, +the `use_field_mapping` parameter is ignored. ==== From 802e21b8a31fb3b7f57917566873d2f8af63c1ab Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:23:08 -0600 Subject: [PATCH 20/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index a7c0e5051be62..e28142cab6907 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -1,7 +1,7 @@ [[rest-api-compatibility]] == REST API compatibility -REST API compatibility in a per-request opt-in feature that can help REST clients mitigate non compatible (breaking) changes to the REST API. +To help REST clients mitigate the impact of non-compatible (breaking) API changes, {es} provides a per-request, opt-in API compatibility mode. {es} REST API's are generally stable across major versions. However, there are cases where {es} REST API's are changed in a non compatible ways (breaking) with the prior major version. For example, {es} 7.x supported custom mapping types in many of the URL paths, but {es} 8.0+ does not support From 4ae22d8726eef95275fe5d617a38f0cbdc6f2138 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:23:22 -0600 Subject: [PATCH 21/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index e28142cab6907..b5416543c0abb 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -3,10 +3,8 @@ To help REST clients mitigate the impact of non-compatible (breaking) API changes, {es} provides a per-request, opt-in API compatibility mode. -{es} REST API's are generally stable across major versions. However, there are cases where {es} REST API's are changed in a non compatible ways (breaking) with the prior major version. -For example, {es} 7.x supported custom mapping types in many of the URL paths, but {es} 8.0+ does not support -custom mapping types (see <>). As a result a REST client that is still using custom types in the -URL paths to communicating with {es} 8.0+ will error. If requested, REST API compatibility can allow that request to succeed even though mapping types are no longer supported. +{es} REST APIs are generally stable across versions. However, some improvements require changes that are not compatible with previous versions. +For example, {es} 7.x supported custom mapping types in many URL paths, but {es} 8.0+ does not (see <>). Specifying a custom type in a request sent to {es} 8.0+ returns an error. However, if you request REST API compatibility, {es} accepts the request even though mapping types are no longer supported. All non compatible (breaking) changes to the {es} REST API will be deprecated in the prior major version to where the non compatible (breaking) change occurs. For example, if a REST API is removed (or changed in some non compatible way) in 8.x it will be will be deprecated in 7.x and will emit deprecation logs anytime that API is invoked. From 45da4c8ab445a06a7cfce5e520d5237d4b7021ae Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:23:34 -0600 Subject: [PATCH 22/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index b5416543c0abb..0cdf06bf821f0 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -6,8 +6,7 @@ To help REST clients mitigate the impact of non-compatible (breaking) API change {es} REST APIs are generally stable across versions. However, some improvements require changes that are not compatible with previous versions. For example, {es} 7.x supported custom mapping types in many URL paths, but {es} 8.0+ does not (see <>). Specifying a custom type in a request sent to {es} 8.0+ returns an error. However, if you request REST API compatibility, {es} accepts the request even though mapping types are no longer supported. -All non compatible (breaking) changes to the {es} REST API will be deprecated in the prior major version to where the non compatible (breaking) change occurs. -For example, if a REST API is removed (or changed in some non compatible way) in 8.x it will be will be deprecated in 7.x and will emit deprecation logs anytime that API is invoked. +When an API is targeted for removal or is going to be changed in a non-compatible way, the original API is deprecated for one or more releases. Using the original API triggers a deprecation warning in the logs. This provides the opportunity to review the deprecation logs prior to a major version upgrade and take the appropriate actions. However, there are cases where identifying all usages of deprecated APIs could be difficult or impossible. This is where REST API compatibility can help. From 4cf9bd704d3d66c22c72780136c1f1bb945b1210 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:24:01 -0600 Subject: [PATCH 23/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index 0cdf06bf821f0..aea6006089c1e 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -7,8 +7,8 @@ To help REST clients mitigate the impact of non-compatible (breaking) API change For example, {es} 7.x supported custom mapping types in many URL paths, but {es} 8.0+ does not (see <>). Specifying a custom type in a request sent to {es} 8.0+ returns an error. However, if you request REST API compatibility, {es} accepts the request even though mapping types are no longer supported. When an API is targeted for removal or is going to be changed in a non-compatible way, the original API is deprecated for one or more releases. Using the original API triggers a deprecation warning in the logs. -This provides the opportunity to review the deprecation logs prior to a major version upgrade and take the appropriate actions. However, there are cases where -identifying all usages of deprecated APIs could be difficult or impossible. This is where REST API compatibility can help. +This enables you to review the deprecation logs and take the appropriate actions before upgrading. However, in some cases it is difficult to +identify all places where deprecated APIs are being used. This is where REST API compatibility can help. When requested, REST API compatibility instructs the {es} server to attempt to honor the REST API of the prior major version. For most API's REST API compatibility has no effect. Requests for compatibility only impacts APIs that have non compatible (breaking) changes from the prior major version. From 1713dc56cc00ad356e7f7ea48501a8bad7d7d2e2 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:24:35 -0600 Subject: [PATCH 24/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- .../rest-api/rest-api-compatibility.asciidoc | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index aea6006089c1e..a5c6dec519e81 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -10,11 +10,13 @@ When an API is targeted for removal or is going to be changed in a non-compatibl This enables you to review the deprecation logs and take the appropriate actions before upgrading. However, in some cases it is difficult to identify all places where deprecated APIs are being used. This is where REST API compatibility can help. -When requested, REST API compatibility instructs the {es} server to attempt to honor the REST API of the prior major version. -For most API's REST API compatibility has no effect. Requests for compatibility only impacts APIs that have non compatible (breaking) changes from the prior major version. -For example, custom mapping types were supported in URL paths for 7.x, but are not supported in 8.x. When compatibility is requested {es} will internally and automatically redirect any URL that -includes the custom mapping type to it's non-typed equivalent URL. In this case, requesting compatibility effectively ignores the custom mapping type of the requested URL. -Additionally, for requests that would have warranted a response that in 7.x that included a type field REST API compatibility will inject a _type field with a hard coded value of _doc as part of the response. +When you request REST API compatibility, {es} attempts to honor the previous REST API version. +{es} attempts to apply the most compatible URL, request body, response body, and HTTP parameters. + +For compatible APIs, this has no effect--it only impacts calls to APIs that have breaking changes from the previous version. +An error can still be returned in compatibility mode if {es} cannot automatically resolve the incompatibilities, + +IMPORTANT: REST API compatibility does not guarantee the same behavior as the prior version. It instructs {es} to automatically resolve any incompatibilities so the request can be processed instead of returning an error. It is important to note that REST API compatibility does not result in the same behavior as the prior version. Rather REST API compatibility is a best effort by the {es} service to find the best way to automatically resolve any incompatibility introduced in the REST API. From a83824370726bb96310b887a715e7dfa8c5a71b1 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:24:44 -0600 Subject: [PATCH 25/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index a5c6dec519e81..1b7594237169b 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -19,8 +19,7 @@ An error can still be returned in compatibility mode if {es} cannot automaticall IMPORTANT: REST API compatibility does not guarantee the same behavior as the prior version. It instructs {es} to automatically resolve any incompatibilities so the request can be processed instead of returning an error. -It is important to note that REST API compatibility does not result in the same behavior as the prior version. Rather REST API compatibility is a best effort by the {es} service to find the best way to automatically resolve any incompatibility introduced in the REST API. -This level of compatibility may not work for all workflows and use cases. For example, if the custom mapping types are an integral part of a workflow then ignoring the custom type at the REST API will not help. +REST API compatibility should be a bridge to smooth out the upgrade process, not a long term strategy. REST API compatibility is only honored across one major version: honor 7.x requests/responses from 8.x. When you submit requests using REST API compatibility and {es} resolves the incompatibility, a message is written to the deprecation log with the category "compatible_api". Review the deprecation log to identify any gaps in usage and fully supported features. From 367c8603d62e9c7b4b979539f2c081ddf0502bd2 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:41:52 -0600 Subject: [PATCH 26/30] line breaks --- .../rest-api/rest-api-compatibility.asciidoc | 75 +++++++++++++------ 1 file changed, 52 insertions(+), 23 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index 1b7594237169b..42a6f667cbc45 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -1,36 +1,58 @@ [[rest-api-compatibility]] == REST API compatibility -To help REST clients mitigate the impact of non-compatible (breaking) API changes, {es} provides a per-request, opt-in API compatibility mode. +To help REST clients mitigate the impact of non-compatible (breaking) +API changes, {es} provides a per-request, opt-in API compatibility mode. -{es} REST APIs are generally stable across versions. However, some improvements require changes that are not compatible with previous versions. -For example, {es} 7.x supported custom mapping types in many URL paths, but {es} 8.0+ does not (see <>). Specifying a custom type in a request sent to {es} 8.0+ returns an error. However, if you request REST API compatibility, {es} accepts the request even though mapping types are no longer supported. +{es} REST APIs are generally stable across versions. However, some +improvements require changes that are not compatible with previous versions. +For example, {es} 7.x supported custom mapping types in many URL paths, +but {es} 8.0+ does not (see <>). Specifying a custom type +in a request sent to {es} 8.0+ returns an error. However, if you request +REST API compatibility, {es} accepts the request even though mapping types +are no longer supported. -When an API is targeted for removal or is going to be changed in a non-compatible way, the original API is deprecated for one or more releases. Using the original API triggers a deprecation warning in the logs. -This enables you to review the deprecation logs and take the appropriate actions before upgrading. However, in some cases it is difficult to -identify all places where deprecated APIs are being used. This is where REST API compatibility can help. +When an API is targeted for removal or is going to be changed in a +non-compatible way, the original API is deprecated for one or more releases. +Using the original API triggers a deprecation warning in the logs. +This enables you to review the deprecation logs and take the appropriate actions +before upgrading. However, in some cases it is difficult to +identify all places where deprecated APIs are being used. This is where REST API +compatibility can help. -When you request REST API compatibility, {es} attempts to honor the previous REST API version. -{es} attempts to apply the most compatible URL, request body, response body, and HTTP parameters. +When you request REST API compatibility, {es} attempts to honor the previous +REST API version. {es} attempts to apply the most compatible URL, request body, +response body, and HTTP parameters. -For compatible APIs, this has no effect--it only impacts calls to APIs that have breaking changes from the previous version. -An error can still be returned in compatibility mode if {es} cannot automatically resolve the incompatibilities, +For compatible APIs, this has no effect--it only impacts calls to APIs +that have breaking changes from the previous version. An error can still be +returned in compatibility mode if {es} cannot automatically resolve the incompatibilities. -IMPORTANT: REST API compatibility does not guarantee the same behavior as the prior version. It instructs {es} to automatically resolve any incompatibilities so the request can be processed instead of returning an error. +IMPORTANT: REST API compatibility does not guarantee the same behavior +as the prior version. It instructs {es} to automatically resolve any +incompatibilities so the request can be processed instead of returning an error. -REST API compatibility should be a bridge to smooth out the upgrade process, not a long term strategy. REST API compatibility is only honored across one major version: honor 7.x requests/responses from 8.x. +REST API compatibility should be a bridge to smooth out the upgrade process, +not a long term strategy. REST API compatibility is only honored across one +major version: honor 7.x requests/responses from 8.x. -When you submit requests using REST API compatibility and {es} resolves the incompatibility, a message is written to the deprecation log with the category "compatible_api". Review the deprecation log to identify any gaps in usage and fully supported features. +When you submit requests using REST API compatibility and {es} resolves +the incompatibility, a message is written to the deprecation log with +the category "compatible_api". Review the deprecation log to identify +any gaps in usage and fully supported features. -For information about specific breaking changes and the impact of requesting compatibility mode, see <> in the migration guide. +For information about specific breaking changes and the impact of requesting +compatibility mode, see <> +in the migration guide. [discrete] [[request-rest-api-compatibility]] === Requesting REST API compatibility -REST API compatibility is implemented per request via the Accept and/or Content-Type headers. +REST API compatibility is implemented per request via the Accept +and/or Content-Type headers. For example: @@ -40,8 +62,9 @@ Accept: "application/vnd.elasticsearch+json;compatible-with=7" Content-Type: "application/vnd.elasticsearch+json;compatible-with=7" ------------------------------------------------------------ -The Accept header is always required and the Content-Type header is only required when a body is sent with the request. -The following values are valid when communicating with a 7.x or 8.x {es} server: +The Accept header is always required and the Content-Type header is +only required when a body is sent with the request. The following values are +valid when communicating with a 7.x or 8.x {es} server: [source, text] ------------------------------------------------------------ "application/vnd.elasticsearch+json;compatible-with=7" @@ -49,19 +72,25 @@ The following values are valid when communicating with a 7.x or 8.x {es} server: "application/vnd.elasticsearch+smile;compatible-with=7" "application/vnd.elasticsearch+cbor;compatible-with=7" ------------------------------------------------------------ -The [link:/guide](https://www.elastic.co/guide/en/elasticsearch/client/index.html)[officially supported {es} clients] can enable REST API compatibility for all requests. +The [link:/guide](https://www.elastic.co/guide/en/elasticsearch/client/index.html)[officially supported {es} clients] +can enable REST API compatibility for all requests. -To enable REST API compatibility for all requests received by {es} set the environment variable `ELASTIC_CLIENT_APIVERSIONING` to true. +To enable REST API compatibility for all requests received +by {es} set the environment variable `ELASTIC_CLIENT_APIVERSIONING` to true. [discrete] === REST API compatibility workflow To leverage REST API compatibility during an upgrade from 7.17 to {version}: -1. Upgrade your https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} clients] to the latest 7.x version and enable REST API compatibility. -2. Use the {kibana-ref}/upgrade-assistant.html[Upgrade Assistant] to review all critical issues and explore the deprecation logs. Some critical issues might be mitigated by REST API compatibility. +1. Upgrade your https://www.elastic.co/guide/en/elasticsearch/client/index.html[{es} clients] +to the latest 7.x version and enable REST API compatibility. +2. Use the {kibana-ref}/upgrade-assistant.html[Upgrade Assistant] +to review all critical issues and explore the deprecation logs. +Some critical issues might be mitigated by REST API compatibility. 3. Resolve all critical issues before proceeding with the upgrade. 4. Upgrade Elasticsearch to {version}. -5. Review the deprecation logs for entries with the category `compatible_api1`. Review the workflow associated with the requests that relied on compatibility mode. -6. Upgrade your {es} clients to 8.x and resolve compatibility issues manually where needed. +5. Review the deprecation logs for entries with the category `compatible_api`. +Review the workflow associated with the requests that relied on compatibility mode. +6. Upgrade your {es} clients to 8.x and resolve compatibility issues manually where needed. From 9c248e42a160cf38beabdb192a70104e5a2d8f42 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 11:45:32 -0600 Subject: [PATCH 27/30] remove whitespace --- docs/reference/upgrade.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/upgrade.asciidoc b/docs/reference/upgrade.asciidoc index 75071c3d4ca52..3b2de92e2c6f8 100644 --- a/docs/reference/upgrade.asciidoc +++ b/docs/reference/upgrade.asciidoc @@ -5,12 +5,12 @@ -- ifeval::["{release-state}"!="released"] [[upgrade-pre-release]] -IMPORTANT: This documentation is for a pre-release of {es} {minor-version}. +IMPORTANT: This documentation is for a pre-release of {es} {minor-version}. Upgrades from pre-release builds are not supported and -could result in errors or data loss. -If you upgrade from a released version to a pre-release verion for testing, +could result in errors or data loss. +If you upgrade from a released version to a pre-release verion for testing, discard the contents of the cluster when you are done. -Do not attempt to upgrade to the final release. +Do not attempt to upgrade to the final release. endif::[] {es} can usually be upgraded using a <> @@ -44,7 +44,7 @@ other functionality that may have changed. [cols="<1,3",options="header",] |==== -|Upgrade from +|Upgrade from |Recommended upgrade path to {version} ifeval::[ "{bare_version}" != "{minor-version}.0" ] From e51189b9c0555c8d83113cf009c26f2689ec7d88 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 14:13:04 -0600 Subject: [PATCH 28/30] added todo to fix broken link --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index 42a6f667cbc45..5046f8165f86b 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -72,7 +72,12 @@ valid when communicating with a 7.x or 8.x {es} server: "application/vnd.elasticsearch+smile;compatible-with=7" "application/vnd.elasticsearch+cbor;compatible-with=7" ------------------------------------------------------------ -The [link:/guide](https://www.elastic.co/guide/en/elasticsearch/client/index.html)[officially supported {es} clients] + +The TODO: fix the link +[source, text] +------------------------------------------------------------ +[link:/guide](https://www.elastic.co/guide/en/elasticsearch/client/index.html)[officially supported {es} clients] +------------------------------------------------------------ can enable REST API compatibility for all requests. To enable REST API compatibility for all requests received From ed669b3e8a1d4ce54c90fc2ff15b5c1d61c8b3dc Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 14:14:05 -0600 Subject: [PATCH 29/30] Revert "added todo to fix broken link" This reverts commit e51189b9c0555c8d83113cf009c26f2689ec7d88. --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index 5046f8165f86b..42a6f667cbc45 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -72,12 +72,7 @@ valid when communicating with a 7.x or 8.x {es} server: "application/vnd.elasticsearch+smile;compatible-with=7" "application/vnd.elasticsearch+cbor;compatible-with=7" ------------------------------------------------------------ - -The TODO: fix the link -[source, text] ------------------------------------------------------------- -[link:/guide](https://www.elastic.co/guide/en/elasticsearch/client/index.html)[officially supported {es} clients] ------------------------------------------------------------- +The [link:/guide](https://www.elastic.co/guide/en/elasticsearch/client/index.html)[officially supported {es} clients] can enable REST API compatibility for all requests. To enable REST API compatibility for all requests received From 17f423f70ec37d3ac54f216a9be743e13fe27852 Mon Sep 17 00:00:00 2001 From: Jake Landis Date: Fri, 4 Feb 2022 16:12:26 -0600 Subject: [PATCH 30/30] Update docs/reference/rest-api/rest-api-compatibility.asciidoc Co-authored-by: debadair --- docs/reference/rest-api/rest-api-compatibility.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/rest-api/rest-api-compatibility.asciidoc b/docs/reference/rest-api/rest-api-compatibility.asciidoc index 42a6f667cbc45..39db48e36691a 100644 --- a/docs/reference/rest-api/rest-api-compatibility.asciidoc +++ b/docs/reference/rest-api/rest-api-compatibility.asciidoc @@ -72,7 +72,7 @@ valid when communicating with a 7.x or 8.x {es} server: "application/vnd.elasticsearch+smile;compatible-with=7" "application/vnd.elasticsearch+cbor;compatible-with=7" ------------------------------------------------------------ -The [link:/guide](https://www.elastic.co/guide/en/elasticsearch/client/index.html)[officially supported {es} clients] +The https://www.elastic.co/guide/en/elasticsearch/client/index.html[officially supported {es} clients] can enable REST API compatibility for all requests. To enable REST API compatibility for all requests received