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

[[java-rest-high-usage]]
== Getting started

This section describes how to get started with the high-level REST client from
getting the artifact to using it in an application.

[[java-rest-high-compatibility]]
=== Compatibility
The Java High Level REST Client requires Java 1.8 and depends on the Elasticsearch
core project. The client version is the same as the Elasticsearch version that the
client was developed for. It accepts the same request arguments as the `TransportClient`
and returns the same response objects.

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.

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

The javadoc for the REST high level client can be found at {rest-high-level-client-javadoc}/index.html.

[[java-rest-high-usage-maven]]
=== Maven Repository

The high-level Java REST client is hosted on
http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Maven
Central]. The minimum Java version required is `1.8`.

The High Level REST Client is subject to the same release cycle as
Elasticsearch. Replace the version with the desired client version.

[[java-rest-high-usage-maven-maven]]
==== Maven configuration

Here is how you can configure the dependency using maven as a dependency manager.
Add the following to your `pom.xml` file:

["source","xml",subs="attributes"]
--------------------------------------------------
<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>{version}</version>
</dependency>
--------------------------------------------------

[[java-rest-high-usage-maven-gradle]]
==== Gradle configuration

Here is how you can configure the dependency using gradle as a dependency manager.
Add the following to your `build.gradle` file:

["source","groovy",subs="attributes"]
--------------------------------------------------
dependencies {
    compile 'org.elasticsearch.client:elasticsearch-rest-high-level-client:{version}'
}
--------------------------------------------------

[[java-rest-high-usage-maven-lucene]]
==== Lucene Snapshot repository

The very first releases of any major version (like a beta), might have been built on top of a Lucene Snapshot version.
In such a case you will be unable to resolve the Lucene dependencies of the client.

For example, if you want to use the `6.0.0-beta1` version which depends on Lucene `7.0.0-snapshot-00142c9`, you must
define the following repository.

For Maven:

["source","xml",subs="attributes"]
--------------------------------------------------
<repository>
    <id>elastic-lucene-snapshots</id>
    <name>Elastic Lucene Snapshots</name>
    <url>http://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>false</enabled></snapshots>
</repository>
--------------------------------------------------

For Gradle:

["source","groovy",subs="attributes"]
--------------------------------------------------
maven {
    url 'http://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9'
}
--------------------------------------------------

[[java-rest-high-usage-dependencies]]
=== Dependencies

The High Level Java REST Client depends on the following artifacts and their
transitive dependencies:

- org.elasticsearch.client:elasticsearch-rest-client
- org.elasticsearch:elasticsearch


[[java-rest-high-usage-initialization]]
=== Initialization

A `RestHighLevelClient` instance needs a <<java-rest-low-usage-initialization,REST low-level client>>
to be built as follows:

[source,java]
--------------------------------------------------
RestHighLevelClient client =
    new RestHighLevelClient(lowLevelRestClient); <1>
--------------------------------------------------
<1> We pass the <<java-rest-low-usage-initialization,REST low-level client>> instance

In the rest of this documentation about the Java High Level Client, the `RestHighLevelClient` instance
will be referenced as `client`.