Skip to content

Commit f3d109b

Browse files
authored
[DOCS] Clarify compatibility and relation between high level REST client and core version (#26279)
Closes #26142
1 parent 4bce727 commit f3d109b

File tree

1 file changed

+21
-9
lines changed

1 file changed

+21
-9
lines changed

docs/java-rest/high-level/usage.asciidoc

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,27 @@ getting the artifact to using it in an application.
99
The Java High Level REST Client requires Java 1.8 and depends on the Elasticsearch
1010
core project. The client version is the same as the Elasticsearch version that the
1111
client was developed for. It accepts the same request arguments as the `TransportClient`
12-
and returns the same response objects.
13-
14-
The High Level Client is backwards compatible but can only communicate with Elasticsearch
15-
version 5.5 and onwards. The High Level Client is forward compatible as well, meaning that
16-
it supports communicating with a later version of Elasticsearch than the one it was developed
17-
for. It is recommended to upgrade the High Level Client when upgrading the Elasticsearch
18-
cluster to a new major version, as REST API breaking changes may cause unexpected results,
19-
and newly added APIs will only be supported by the newer version of the client. The client
20-
should be updated last, once all of the nodes in the cluster have been upgraded.
12+
and returns the same response objects. See the <<java-rest-high-level-migration>>
13+
if you need to migrate an application from `TransportClient` to the new REST client.
14+
15+
The High Level Client is guaranteed to be able to communicate with any Elasticsearch
16+
node running on the same major version and greater or equal minor version. It
17+
doesn't need to be in the same minor version as the Elasticsearch nodes it
18+
communicates with, as it is forward compatible meaning that it supports
19+
communicating with later versions of Elasticsearch than the one it was developed for.
20+
21+
The 6.0 client is able to communicate with any 6.x Elasticsearch node, while the 6.1
22+
client is for sure able to communicate with 6.1, 6.2 and any later 6.x version, but
23+
there may be incompatibility issues when communicating with a previous Elasticsearch
24+
node version, for instance between 6.1 and 6.0, in case the 6.1 client supports new
25+
request body fields for some APIs that are not known by the 6.0 node(s).
26+
27+
It is recommended to upgrade the High Level Client when upgrading the Elasticsearch
28+
cluster to a new major version, as REST API breaking changes may cause unexpected
29+
results depending on the node that is hit by the request, and newly added APIs will
30+
only be supported by the newer version of the client. The client should always be
31+
updated last, once all of the nodes in the cluster have been upgraded to the new
32+
major version.
2133

2234
[[java-rest-high-javadoc]]
2335
=== Javadoc

0 commit comments

Comments
 (0)