It isn't really a Create, Read, Update, or Delete operation so maybe it should be in its own test just for naming's sake.

I'd s/always//.

It doesn't use Java serialization, right? I mean, it uses a our home grown binary serialization.

Absolutely... I had trouble to find the right phrase and in the end it ended with something wrong :/

I wouldn't say it is perfect - it is acceptable, but it ties the user application quite tightly to Elasticsearch.

I agree - I changed perfect for acceptable. Let me know if you think the whole sentence should be reworded.

missing space.

It has more than two transitive dependencies because it has Elasticsearch's dependencies too.

Oh right - I replaced two transitive dependencies by dependencies as I find it simpler to understand.

which sends HTTP requests instead of using the transport layer.

Now is actually a good time to deprecate it :) Feel free to make that change already here or mention that it is deprecated in 6.0

add a link to hl client docs?

add a link to it?

s/many/various kinds of

I wonder what you mean by compatible here. There are breaking changes, and that's why we are working on this page?

Yeah, I agree it's not clear. I rephrased that, I just wanted to say that you can use the client to connect to a cluster in version 5.6.0+.

s/must/can ?

I wonder if this warning is needed. Isn't this kind of implicit given that you never specify the cluster name when specifying the hosts?

By writing this, I wanted to "promote" what I think would be a good practice... on the other side, nothing prevent the user to configure multiple hosts from different clusters :( Let's remove this.

must be replaced is enough?

Adapting existing code ?

gut feeling: these motivations are more for a blogpost that for our docs maybe? I would rather focus on how to migrate here.

I don't know - I added this to add some context around why it's good to migrate, since it's easy to miss a blog post. But I can remove this whole section if you really feel it should not be here.

I like it. Maybe it should be in a blog post as well, but I like explaining it here as too.

ok let's keep it

to replace the TransportClient (remove "the usage")

s/forces/force

This may make people think the the high level client doesn't depend on Elasticsearch, also we don't mention security and wanting to have REST a single entrypoing for a cluster. Shall we link https://www.elastic.co/blog/state-of-the-official-elasticsearch-java-clients that mentions all that and keep this explanation a bit shorter?

We could say:

The TransportClient has been part of Elasticsearch since its very first commit. It is a special client as it uses the transport protocol to communicate with Elasticsearch, which causes compatibility problems if the client is not on the same version as the Elasticsearch instances it talks to.

We released a low-level REST client in 2016, which is based on the well known Apache HTTP client and it allows to communicate with an Elasticsearch cluster in any version using HTTP. On top of that we released the high-level REST client which is based on the low-level client but takes care of request marshalling and response un-marshalling.

Have a look at (here the link) to know more about these changes.

This may make people think the the high level client doesn't depend on Elasticsearch,

Right, this can be a bit confusing and it's hard to resume all the motivations in a single paragraph.

I just borrow your text and let's go!

we should probably more clear on whether it's fine to talk from 5.6.0 to 6.0.0. I guess it is, but new apis won't be known to the client this way. Also breaking changes to the API may cause unexpected results.

I wonder if we have to put the whole maven dependency here, especially given that it's the old one. Maybe we can just say replace the o.e.client:transport dependency with... ?

can we invert the two bullet points, leaving request builders first?

Sure

I would move this paragraph to the end of the page

Makes sense. Should I also move "Checking Cluster Health using the Low-Level REST Client" down?

yes please

and can therefore be used to call the APIs that are not yet supported by the high level client.

Good point too

More importantly

The RestHighLevelClient supports the same request and response object as the TransportClient, but exposes slightly different methods to send the requests.

I would rephrase this:

The Java High Level Rest Client requires Java 1.8 and depends on Elasticsearch core. The client version is the same as the Elasticsearch version that the client was developed for. The High Level Client is backwards compatible but can only communicate with Elasticsearch version 5.5 and onwards. The High Level Client is forward compatible as well, meaning that it supports communicating with a later version of Elasticsearch than the one it was developed for. It is recommended to upgrade the High Level Client when upgrading the Elasticsearch cluster to a new major version, as REST API breaking changes may cause unexpected results, and newly added APIs will only be supported by the newer version of the client. The client should be updated last, once all of the nodes in the cluster have been upgraded.

I am now thinking if this should go somewhere else rather than in the migration guide.

Awesome. I added your text in a "Compatibility" section in the usage page. I created a link in the migration guide to this page.

Sounds great thank you

depends

typically initialized as follows

oops sorry, it shouldn't have been reverted

great!!!!

objects