elasticsearch/docs/java-rest/high-level/getting-started.asciidoc

[[java-rest-high-getting-started]]
== 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 at least 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. See the <<java-rest-high-level-migration>>
if you need to migrate an application from `TransportClient` to the new REST client.

The High Level Client is guaranteed to be able to communicate with any Elasticsearch
node running on the same major version and greater or equal minor version. It
doesn't need to be in the same minor version as the Elasticsearch nodes it
communicates with, as it is forward compatible meaning that it supports
communicating with later versions of Elasticsearch than the one it was developed for.

The 7.0 client is able to communicate with any 7.x Elasticsearch node, while the 7.1
client is for sure able to communicate with 7.1, 7.2 and any later 7.x version, but
there may be incompatibility issues when communicating with a previous Elasticsearch
node version, for instance between 7.1 and 7.0, in case the 7.1 client supports new
request body fields for some APIs that are not known by the 7.0 node(s).

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 depending on the node that is hit by the request, and newly added APIs will
only be supported by the newer version of the client. The client should always be
updated last, once all of the nodes in the cluster have been upgraded to the new
major version.

*Compatibility with Elasticsearch 8.x*

The High Level Client version 7.16 and higher can communicate with Elasticsearch version 8.x after enabling API compatibility mode. When this mode is enabled, the client will send HTTP headers that instruct Elasticsearch 8.x to honor 7.x request/responses.

Compatibility mode is enabled as follows:

["source","java",subs="attributes"]
--------------------------------------------------
RestHighLevelClient esClient = new RestHighLevelClientBuilder(restClient)
    .setApiCompatibilityMode(true)
    .build()
--------------------------------------------------

When compatibility mode is enabled, the client can also communicate with Elasticsearch version 7.11 and higher.

[[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-getting-started-maven]]
=== Maven Repository

The high-level Java REST client is hosted on
https://search.maven.org/search?q=g:org.elasticsearch.client[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.

If you are looking for a SNAPSHOT version, you should add our snapshot repository to your Maven config:

["source","xml",subs="attributes"]
--------------------------------------------------
<repositories>
    <repository>
        <id>es-snapshots</id>
        <name>elasticsearch snapshot repo</name>
        <url>https://snapshots.elastic.co/maven/</url>
    </repository>
</repositories>
--------------------------------------------------

or in Gradle:

["source","groovy",subs="attributes"]
--------------------------------------------------
maven {
        url "https://snapshots.elastic.co/maven/"
}
--------------------------------------------------

[[java-rest-high-getting-started-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-getting-started-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-getting-started-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 `7.0.0-beta1` version which depends on Lucene `8.0.0-snapshot-83f9835`, you must
define the following repository.

For Maven:

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

For Gradle:

["source","groovy",subs="attributes"]
--------------------------------------------------
maven {
    name 'lucene-snapshots'
    url 'https://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/83f9835'
}
--------------------------------------------------

[[java-rest-high-getting-started-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-getting-started-initialization]]
=== Initialization

A `RestHighLevelClient` instance needs a
{java-api-client}/java-rest-low-usage-initialization.html[REST low-level client builder]
to be built as follows:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-init]
--------------------------------------------------

The high-level client will internally create the low-level client used to
perform requests based on the provided builder. That low-level client
maintains a pool of connections and starts some threads so you should
close the high-level client when you are well and truly done with
it and it will in turn close the internal low-level client to free those
resources. This can be done through the `close`:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-close]
--------------------------------------------------

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

[[java-rest-high-getting-started-request-options]]
=== RequestOptions

All APIs in the `RestHighLevelClient` accept a `RequestOptions` which you can
use to customize the request in ways that won't change how Elasticsearch
executes the request. For example, this is the place where you'd specify a
`NodeSelector` to control which node receives the request. See the
{java-api-client}/java-rest-low-usage-requests.html#java-rest-low-usage-request-options[low level client documentation]
for more examples of customizing the options.

[[java-rest-high-getting-started-asynchronous-usage]]
=== Asynchronous usage

All of the methods across the different clients exist in a traditional synchronous and
asynchronous variant. The difference is that the asynchronous ones use asynchronous requests
in the REST Low Level Client. This is useful if you are doing multiple requests or are using e.g.
rx java, Kotlin co-routines, or similar frameworks.

The asynchronous methods are recognizable by the fact that they have the word "Async" in their name
and return a `Cancellable` instance. The asynchronous methods accept the same request object
as the synchronous variant and accept a generic `ActionListener<T>` where `T` is the return
type of the synchronous method.

All asynchronous methods return a `Cancellable` object with a `cancel` method that you may call
in case you want to abort the request. Cancelling
no longer needed requests is a good way to avoid putting unnecessary
load on Elasticsearch.

Using the `Cancellable` instance is optional and you can safely ignore this if you have
no need for this. A use case for this would be using this with e.g. Kotlin's `suspendCancellableCoRoutine`.