Remove documentation for High Level Rest Client [DOC]

[wbeckler]

What do you want to do?

• [ X ] Request a change to existing documentation

Tell us about your request. Provide a summary of the request and all versions that are affected.

We have a section on the High Level Rest Client: https://opensearch.org/docs/latest/clients/java-rest-high-level/

In fact this client is not recommended. It will likely be deprecated. There are several challenges to people relying on that client. It is not receiving updates or features at the same rate as the supported client, opensearch-java. It may malfunction if a user does not want to upgrade their jvm for their clients when they need to update their server version (see #1975).

This request is to simply remove the reference to the High Level Rest Client on the docs website.

What other resources are available? Provide links to related issues, POCs, steps for testing, etc.
The opensearch-java client is the correct resource, and we already document that.

[hdhalter]

Hi @Naarcha-AWS , Fanit said she'll take care of this.

[wbeckler]

Seeking feedback on this issue from @reta and @dblock

[reta]

Seeking feedback on this issue from @reta and @dblock

I believe for 3.0.0 we have to update documentation with deprecation notice. People do use RHCL right now and without this intermediate step (of deprecation) we leave them no time to migrate.

[wbeckler]

How about marking the documentation with advance warning to prevent further investment

…

On Thu, Dec 22, 2022, 7:27 PM Andriy Redko ***@***.***> wrote: Seeking feedback on this issue from @reta <https://github.com/reta> and @dblock <https://github.com/dblock> I believe for 3.0.0 we have to update documentation with deprecation notice. People do use RHCL right now and without this intermediate step (of deprecation) we leave them no time to migrate. — Reply to this email directly, view it on GitHub <#2010 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA5PRLXE4SYK3YKTBCHCICTWOTWXVANCNFSM6AAAAAASHKCK2Q> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>

[reta]

Sure, that what the deprecation would have meant to emphasize :) This is pretty standard way for OpenSearch to phase off features and components.

[dbwiddis]

How about marking the documentation with advance warning to prevent further investment

Please leave the documentation as reference with clear documentation not to use it for new development!

[andrross]

Agree on updating the documentation to mark the high level REST client as deprecated. Currently both clients show up in the left-hand navigation and it is not at all obvious which one to prefer or even why two of them exist.

@reta Is there any reason why we can't start nudging users to opensearch-java now (as opposed to starting in 3.0) with a deprecation notice in the documentation on the high-level REST client?

[reta]

Agree on updating the documentation to mark the high level REST client as deprecated. Currently both clients show up in the left-hand navigation and it is not at all obvious which one to prefer or even why two of them exist.

@reta Is there any reason why we can't start nudging users to opensearch-java now (as opposed to starting in 3.0) with a deprecation notice in the documentation on the high-level REST client?

@andrross I think we could start with deprecation now, non-issue, but we are half way through 2.x release (2.5 is coming out), I think we may not give people enough time to jump off the RestHighLevelClient (fe timing the deprecation with 2.0 would give much more time). The thing to keep in mind also is that we do have many projects (under OpenSearch umbrella and outside) where RestHighLevelClient is used, we may not even have time to phase out RestHighLevelClient in those before 3.0.0.

[andrross]

@reta Agreed that removing RestHighLevelClient will likely be difficult because it is widely used so we may end up keeping it around for awhile, but that shouldn't stop us from getting the desired guidance and deprecations in the documentation now.

[kolchfa-aws]

Now that 2.5 is out, how about adding the following warning to the high-level REST client:
The OpenSearch Java high-level REST client will be deprecated starting with OpenSearch version 3.0.0 and will be removed in a future release. We recommend switching to the [Java client](https://opensearch.org/docs/latest/clients/java/) instead.