[DOCS] add docs for REST high level client index method (#25501)

This commit restructures the existing high level client docs, adapts the existing delete method docs and adds docs for the index method.

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java

@@ -0,0 +1,321 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client.documentation;
+
+import org.elasticsearch.ElasticsearchException;
+import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.action.DocWriteRequest;
+import org.elasticsearch.action.DocWriteResponse;
+import org.elasticsearch.action.delete.DeleteRequest;
+import org.elasticsearch.action.delete.DeleteResponse;
+import org.elasticsearch.action.index.IndexRequest;
+import org.elasticsearch.action.index.IndexResponse;
+import org.elasticsearch.action.support.WriteRequest;
+import org.elasticsearch.action.support.replication.ReplicationResponse;
+import org.elasticsearch.client.ESRestHighLevelClientTestCase;
+import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.common.unit.TimeValue;
+import org.elasticsearch.common.xcontent.XContentBuilder;
+import org.elasticsearch.common.xcontent.XContentFactory;
+import org.elasticsearch.common.xcontent.XContentType;
+import org.elasticsearch.index.VersionType;
+import org.elasticsearch.rest.RestStatus;
+
+import java.io.IOException;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * This class is used to generate the Java CRUD API documentation.
+ * You need to wrap your code between two tags like:
+ * // tag::example[]
+ * // end::example[]
+ *
+ * Where example is your tag name.
+ *
+ * Then in the documentation, you can extract what is between tag and end tags with
+ * ["source","java",subs="attributes,callouts,macros"]
+ * --------------------------------------------------
+ * include-tagged::{doc-tests}/CRUDDocumentationIT.java[example]
+ * --------------------------------------------------
+ */
+public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
+
+    public void testIndex() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+
+        {
+            //tag::index-request-map
+            Map<String, Object> jsonMap = new HashMap<>();
+            jsonMap.put("user", "kimchy");
+            jsonMap.put("postDate",new Date());
+            jsonMap.put("message","trying out Elasticsearch");
+            IndexRequest indexRequest = new IndexRequest("index", "type", "id")
+                    .source(jsonMap); // <1>
+            //end::index-request-map
+            IndexResponse indexResponse = client.index(indexRequest);
+            assertEquals(indexResponse.getResult(), DocWriteResponse.Result.CREATED);
+        }
+        {
+            //tag::index-request-xcontent
+            XContentBuilder builder = XContentFactory.jsonBuilder();
+            builder.startObject();
+            {
+                builder.field("user", "kimchy");
+                builder.field("postDate", new Date());
+                builder.field("message", "trying out Elasticsearch");
+            }
+            builder.endObject();
+            IndexRequest indexRequest = new IndexRequest("index", "type", "id")
+                    .source(builder);  // <1>
+            //end::index-request-xcontent
+            IndexResponse indexResponse = client.index(indexRequest);
+            assertEquals(indexResponse.getResult(), DocWriteResponse.Result.UPDATED);
+        }
+        {
+            //tag::index-request-shortcut
+            IndexRequest indexRequest = new IndexRequest("index", "type", "id")
+                    .source("user", "kimchy",
+                            "postDate", new Date(),
+                            "message", "trying out Elasticsearch"); // <1>
+            //end::index-request-shortcut
+            IndexResponse indexResponse = client.index(indexRequest);
+            assertEquals(indexResponse.getResult(), DocWriteResponse.Result.UPDATED);
+        }
+        {
+            //tag::index-request-string
+            IndexRequest request = new IndexRequest(
+                    "index", // <1>
+                    "type",  // <2>
+                    "id");   // <3>
+            String jsonString = "{" +
+                    "\"user\":\"kimchy\"," +
+                    "\"postDate\":\"2013-01-30\"," +
+                    "\"message\":\"trying out Elasticsearch\"" +
+                    "}";
+            request.source(jsonString, XContentType.JSON); //<4>
+            //end::index-request-string
+
+            // tag::index-execute
+            IndexResponse indexResponse = client.index(request);
+            // end::index-execute
+            assertEquals(indexResponse.getResult(), DocWriteResponse.Result.UPDATED);
+
+            // tag::index-response
+            String index = indexResponse.getIndex();
+            String type = indexResponse.getType();
+            String id = indexResponse.getId();
+            long version = indexResponse.getVersion();
+            if (indexResponse.getResult() == DocWriteResponse.Result.CREATED) {
+                // <1>
+            } else if (indexResponse.getResult() == DocWriteResponse.Result.UPDATED) {
+                // <2>
+            }
+            ReplicationResponse.ShardInfo shardInfo = indexResponse.getShardInfo();
+            if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
+                // <3>
+            }
+            if (shardInfo.getFailed() > 0) {
+                for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
+                    String reason = failure.reason(); // <4>
+                }
+            }
+            // end::index-response
+
+            // tag::index-execute-async
+            client.indexAsync(request, new ActionListener<IndexResponse>() {
+                @Override
+                public void onResponse(IndexResponse indexResponse) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            });
+            // end::index-execute-async
+        }
+        {
+            IndexRequest request = new IndexRequest("index", "type", "id");
+            // tag::index-request-routing
+            request.routing("routing"); // <1>
+            // end::index-request-routing
+            // tag::index-request-parent
+            request.parent("parent"); // <1>
+            // end::index-request-parent
+            // tag::index-request-timeout
+            request.timeout(TimeValue.timeValueSeconds(1)); // <1>
+            request.timeout("1s"); // <2>
+            // end::index-request-timeout
+            // tag::index-request-refresh
+            request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // <1>
+            request.setRefreshPolicy("wait_for");                            // <2>
+            // end::index-request-refresh
+            // tag::index-request-version
+            request.version(2); // <1>
+            // end::index-request-version
+            // tag::index-request-version-type
+            request.versionType(VersionType.EXTERNAL); // <1>
+            // end::index-request-version-type
+            // tag::index-request-op-type
+            request.opType(DocWriteRequest.OpType.CREATE); // <1>
+            request.opType("create"); // <2>
+            // end::index-request-op-type
+            // tag::index-request-pipeline
+            request.setPipeline("pipeline"); // <1>
+            // end::index-request-pipeline
+        }
+        {
+            // tag::index-conflict
+            IndexRequest request = new IndexRequest("index", "type", "id")
+                    .source("field", "value")
+                    .version(1);
+            try {
+                IndexResponse response = client.index(request);
+            } catch(ElasticsearchException e) {
+                if (e.status() == RestStatus.CONFLICT) {
+                    // <1>
+                }
+            }
+            // end::index-conflict
+
+        }
+        {
+            // tag::index-optype
+            IndexRequest request = new IndexRequest("index", "type", "id")
+                    .source("field", "value")
+                    .opType(DocWriteRequest.OpType.CREATE);
+            try {
+                IndexResponse response = client.index(request);
+            } catch(ElasticsearchException e) {
+                if (e.status() == RestStatus.CONFLICT) {
+                    // <1>
+                }
+            }
+            // end::index-optype
+        }
+    }
+
+    public void testDelete() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+
+        {
+            IndexRequest indexRequest = new IndexRequest("index", "type", "id").source("field", "value");
+            IndexResponse indexResponse = client.index(indexRequest);
+            assertSame(indexResponse.status(), RestStatus.CREATED);
+        }
+
+        {
+            // tag::delete-request
+            DeleteRequest request = new DeleteRequest(
+                    "index",    // <1>
+                    "type",     // <2>
+                    "id");      // <3>
+            // end::delete-request
+
+            // tag::delete-execute
+            DeleteResponse deleteResponse = client.delete(request);
+            // end::delete-execute
+            assertSame(deleteResponse.getResult(), DocWriteResponse.Result.DELETED);
+
+            // tag::delete-response
+            String index = deleteResponse.getIndex();
+            String type = deleteResponse.getType();
+            String id = deleteResponse.getId();
+            long version = deleteResponse.getVersion();
+            ReplicationResponse.ShardInfo shardInfo = deleteResponse.getShardInfo();
+            if (shardInfo.getTotal() != shardInfo.getSuccessful()) {
+                //<1>
+            }
+            if (shardInfo.getFailed() > 0) {
+                for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
+                    String reason = failure.reason(); // <2>
+                }
+            }
+            // end::delete-response
+
+            // tag::delete-execute-async
+            client.deleteAsync(request, new ActionListener<DeleteResponse>() {
+                @Override
+                public void onResponse(DeleteResponse deleteResponse) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            });
+            // end::delete-execute-async
+        }
+
+        {
+            DeleteRequest request = new DeleteRequest("index", "type", "id");
+            // tag::delete-request-routing
+            request.routing("routing"); // <1>
+            // end::delete-request-routing
+            // tag::delete-request-parent
+            request.parent("parent"); // <1>
+            // end::delete-request-parent
+            // tag::delete-request-timeout
+            request.timeout(TimeValue.timeValueMinutes(2)); // <1>
+            request.timeout("2m"); // <2>
+            // end::delete-request-timeout
+            // tag::delete-request-refresh
+            request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // <1>
+            request.setRefreshPolicy("wait_for");                            // <2>
+            // end::delete-request-refresh
+            // tag::delete-request-version
+            request.version(2); // <1>
+            // end::delete-request-version
+            // tag::delete-request-version-type
+            request.versionType(VersionType.EXTERNAL); // <1>
+            // end::delete-request-version-type
+        }
+
+        {
+            // tag::delete-notfound
+            DeleteRequest request = new DeleteRequest("index", "type", "does_not_exist");
+            DeleteResponse deleteResponse = client.delete(request);
+            if (deleteResponse.getResult() == DocWriteResponse.Result.NOT_FOUND) {
+                // <1>
+            }
+            // end::delete-notfound
+        }
+
+        {
+            IndexResponse indexResponse = client.index(new IndexRequest("index", "type", "id").source("field", "value"));
+            assertSame(indexResponse.status(), RestStatus.CREATED);
+
+            // tag::delete-conflict
+            try {
+                DeleteRequest request = new DeleteRequest("index", "type", "id").version(2);
+                DeleteResponse deleteResponse = client.delete(request);
+            } catch (ElasticsearchException exception) {
+                if (exception.status() == RestStatus.CONFLICT) {
+                    // <1>
+                }
+            }
+            // end::delete-conflict
+        }
+    }
+}

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java

@@ -1,112 +0,0 @@
-/*
- * Licensed to Elasticsearch under one or more contributor
- * license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright
- * ownership. Elasticsearch licenses this file to you under
- * the Apache License, Version 2.0 (the "License"); you may
- * not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-
-package org.elasticsearch.client.documentation;
-
-import org.elasticsearch.ElasticsearchException;
-import org.elasticsearch.action.ActionListener;
-import org.elasticsearch.action.DocWriteResponse;
-import org.elasticsearch.action.delete.DeleteRequest;
-import org.elasticsearch.action.delete.DeleteResponse;
-import org.elasticsearch.action.support.WriteRequest;
-import org.elasticsearch.client.ESRestHighLevelClientTestCase;
-import org.elasticsearch.client.RestHighLevelClient;
-import org.elasticsearch.common.unit.TimeValue;
-import org.elasticsearch.index.VersionType;
-import org.elasticsearch.rest.RestStatus;
-
-import java.io.IOException;
-
-/**
- * This class is used to generate the Java Delete API documentation.
- * You need to wrap your code between two tags like:
- * // tag::example[]
- * // end::example[]
- *
- * Where example is your tag name.
- *
- * Then in the documentation, you can extract what is between tag and end tags with
- * ["source","java",subs="attributes,callouts"]
- * --------------------------------------------------
- * sys2::[perl -ne 'exit if /end::example/; print if $tag; $tag = $tag || /tag::example/' \
- *     {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java]
- * --------------------------------------------------
- */
-public class DeleteDocumentationIT extends ESRestHighLevelClientTestCase {
-
-    /**
-     * This test documents docs/java-rest/high-level/document/delete.asciidoc
-     */
-    public void testDelete() throws IOException {
-        RestHighLevelClient client = highLevelClient();
-
-        // tag::delete-request
-        DeleteRequest request = new DeleteRequest(
-            "index",    // <1>
-            "type",     // <2>
-            "id");      // <3>
-        // end::delete-request
-
-        // tag::delete-request-props
-        request.timeout(TimeValue.timeValueSeconds(1));                     // <1>
-        request.timeout("1s");                                              // <2>
-        request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL);    // <3>
-        request.setRefreshPolicy("wait_for");                               // <4>
-        request.version(2);                                                 // <5>
-        request.versionType(VersionType.EXTERNAL);                          // <6>
-        // end::delete-request-props
-
-        // tag::delete-execute
-        DeleteResponse response = client.delete(request);
-        // end::delete-execute
-
-        try {
-            // tag::delete-notfound
-            if (response.getResult().equals(DocWriteResponse.Result.NOT_FOUND)) {
-                throw new Exception("Can't find document to be removed"); // <1>
-            }
-            // end::delete-notfound
-        } catch (Exception ignored) { }
-
-        // tag::delete-execute-async
-        client.deleteAsync(request, new ActionListener<DeleteResponse>() {
-            @Override
-            public void onResponse(DeleteResponse deleteResponse) {
-                // <1>
-            }
-
-            @Override
-            public void onFailure(Exception e) {
-                // <2>
-            }
-        });
-        // end::delete-execute-async
-
-        // tag::delete-conflict
-        try {
-            client.delete(request);
-        } catch (ElasticsearchException exception) {
-            if (exception.status().equals(RestStatus.CONFLICT)) {
-                // <1>
-            }
-        }
-        // end::delete-conflict
-
-    }
-}

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

@@ -1,10 +1,19 @@
-* index API
+=== Supported APIs
 
-* get API
+The Java High Level REST Client supports the following APIs:
+
+* <<java-rest-high-document-index>>
+
+* Get API
 
 * <<java-rest-high-document-delete>>
 
-* bulk API
+* Update API
+
+* Bulk API
+
+* Search API
 
-* search API
+* Search Scroll API
 
+* Clear Scroll API

docs/java-rest/high-level/apis/_index.asciidoc

@@ -0,0 +1,151 @@
+[[java-rest-high-document-index]]
+==== Index API
+
+[[java-rest-high-document-index-request]]
+===== Index Request
+
+An `IndexRequest` requires the following arguments:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-string]
+--------------------------------------------------
+<1> Index
+<2> Type
+<3> Document id
+<4> Document source provided as a `String`
+
+===== Providing the document source
+The document source can be provided in different ways:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-map]
+--------------------------------------------------
+<1> Document source provided as a `Map` which gets automatically converted
+to JSON format
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-xcontent]
+--------------------------------------------------
+<1> Document source provided as an `XContentBuilder` object, the Elasticsearch
+built-in helpers to generate JSON content
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-shortcut]
+--------------------------------------------------
+<1> Document source provided as `Object` key-pairs, which gets converted to
+JSON format
+
+===== Optional arguments
+The following arguments can optionally be provided:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-routing]
+--------------------------------------------------
+<1> Routing value
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-parent]
+--------------------------------------------------
+<1> Parent value
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-timeout]
+--------------------------------------------------
+<1> Timeout to wait for primary shard to become available as a `TimeValue`
+<2> Timeout to wait for primary shard to become available as a `String`
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-refresh]
+--------------------------------------------------
+<1> Refresh policy as a `WriteRequest.RefreshPolicy` instance
+<2> Refresh policy as a `String`
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-version]
+--------------------------------------------------
+<1> Version
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-version-type]
+--------------------------------------------------
+<1> Version type
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-op-type]
+--------------------------------------------------
+<1> Operation type provided as an `DocWriteRequest.OpType` value
+<2> Operation type provided as a `String`: can be `create` or `update` (default)
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-pipeline]
+--------------------------------------------------
+<1> The name of the ingest pipeline to be executed before indexing the document
+
+[[java-rest-high-document-index-sync]]
+===== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute]
+--------------------------------------------------
+
+[[java-rest-high-document-index-async]]
+===== Asynchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute-async]
+--------------------------------------------------
+<1> Called when the execution is successfully completed. The response is
+provided as an argument.
+<2> Called in case of failure. The raised exception is provided as an argument.
+
+[[java-rest-high-document-index-response]]
+===== Index Response
+
+The returned `IndexResponse` allows to retrieve information about the executed
+ operation as follows:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-response]
+--------------------------------------------------
+<1> Handle (if needed) the case where the document was created for the first
+time
+<2> Handle (if needed) the case where the document was rewriten as it was
+already existing
+<3> Handle the situation where number of successful shards is less than
+total shards
+<4> Handle the potential failures
+
+If there is a version conflict, an `ElasticsearchException` will
+be thrown:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-conflict]
+--------------------------------------------------
+<1> The raised exception indicates that a version conflict error was returned.
+
+Same will happen in case `opType` was set to `create` and a document with
+same index, type and id already existed:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-optype]
+--------------------------------------------------
+<1> The raised exception indicates that a version conflict error was returned.
+
+

docs/java-rest/high-level/apis/delete.asciidoc

@@ -0,0 +1,108 @@
+[[java-rest-high-document-delete]]
+==== Delete API
+
+[[java-rest-high-document-delete-request]]
+===== Delete Request
+
+A `DeleteRequest` requires the following arguments:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request]
+--------------------------------------------------
+<1> Index
+<2> Type
+<3> Document id
+
+===== Optional arguments
+The following arguments can optionally be provided:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-routing]
+--------------------------------------------------
+<1> Routing value
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-parent]
+--------------------------------------------------
+<1> Parent value
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-timeout]
+--------------------------------------------------
+<1> Timeout to wait for primary shard to become available as a `TimeValue`
+<2> Timeout to wait for primary shard to become available as a `String`
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-refresh]
+--------------------------------------------------
+<1> Refresh policy as a `WriteRequest.RefreshPolicy` instance
+<2> Refresh policy as a `String`
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version]
+--------------------------------------------------
+<1> Version
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version-type]
+--------------------------------------------------
+<1> Version type
+
+[[java-rest-high-document-delete-sync]]
+===== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute]
+--------------------------------------------------
+
+[[java-rest-high-document-delete-async]]
+===== Asynchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute-async]
+--------------------------------------------------
+<1> Called when the execution is successfully completed. The response is
+provided as an argument.
+<2> Called in case of failure. The raised exception is provided as an argument.
+
+[[java-rest-high-document-delete-response]]
+===== Delete Response
+
+The returned `DeleteResponse` allows to retrieve information about the executed
+ operation as follows:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-response]
+--------------------------------------------------
+<1> Handle the situation where number of successful shards is less than
+total shards
+<2> Handle the potential failures
+
+
+It is also possible to check whether the document was found or not:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-notfound]
+--------------------------------------------------
+<1> Do something if the document to be deleted was not found
+
+If there is a version conflict, an `ElasticsearchException` will
+be thrown:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-conflict]
+--------------------------------------------------
+<1> The raised exception indicates that a version conflict error was returned.
+

docs/java-rest/high-level/document/index.asciidoc → docs/java-rest/high-level/apis/index.asciidoc

@@ -1,5 +1,6 @@
 :doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
 
+include::_index.asciidoc[]
 include::delete.asciidoc[]
 
 :doc-tests!:

docs/java-rest/high-level/document/delete.asciidoc

@@ -1,67 +0,0 @@
-[[java-rest-high-document-delete]]
-=== Delete API
-
-[[java-rest-high-document-delete-request]]
-==== Delete Request
-
-The most simple Delete Request needs is:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-request]
---------------------------------------------------
-<1> Index name
-<2> Type
-<3> Document id
-
-
-You can also provide the following properties:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-request-props]
---------------------------------------------------
-<1> Timeout
-<2> Timeout as String
-<3> Refresh policy
-<4> Refresh policy as String
-<5> Version
-<6> Version type
-
-[[java-rest-high-document-delete-sync]]
-==== Execution
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-execute]
---------------------------------------------------
-
-[[java-rest-high-document-delete-async]]
-==== Asynchronous Execution
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-execute-async]
---------------------------------------------------
-<1> Implement if needed when execution did not throw an exception
-<2> Implement if needed in case of failure
-
-[[java-rest-high-document-delete-response]]
-==== Delete Response
-
-In the Delete Response object, you can check for example the result of the operation:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-notfound]
---------------------------------------------------
-<1> Do something if we did not find the document which should have been deleted
-
-Note that if you have a version conflict because you defined the version within the
-<<java-rest-high-document-delete-request>>, it will raise an `ElasticsearchException` like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-conflict]
---------------------------------------------------
-<1> We got a version conflict

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

@@ -1,14 +1,23 @@
 [[java-rest-high]]
 == Java High Level REST Client
 
-The <<java-rest-high>>'s features include:
+The Java High Level REST Client works on top of the Java Low Level REST client.
+Its main goal is to expose API specific methods, that accept request objects as
+an argument and return response objects, so that request marshalling and
+response un-marshalling is handled by the client itself.
 
-include::apis.asciidoc[]
-
-It depends on elasticsearch core project as it uses elasticsearch request and response
-objects so it will simplify a migration from the transport client.
+Each API can be called synchronously or asynchronously. The synchronous
+methods return a response object, while the asynchronous methods, whose names
+end with the `async` suffix, require a listener argument that is notified
+(on the thread pool managed by the low level client) once a response or an
+error is received.
 
+The Java High Level REST Client depends on the Elasticsearch core project.
+It accepts the same request arguments as the `TransportClient` and returns
+the same response objects.
 
 include::usage.asciidoc[]
 
-include::document/index.asciidoc[]
+include::apis.asciidoc[]
+
+include::apis/index.asciidoc[]

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

@@ -8,8 +8,8 @@ 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.
+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
@@ -42,7 +42,7 @@ dependencies {
 [[java-rest-high-usage-dependencies]]
 ==== Dependencies
 
-The high-level Java REST client depends on the following artifacts and their
+The High Level Java REST Client depends on the following artifacts and their
 transitive dependencies:
 
 - org.elasticsearch.client:rest
@@ -62,14 +62,5 @@ RestHighLevelClient client =
 --------------------------------------------------
 <1> We pass the <<java-rest-low-usage-initialization,REST low-level client>> instance
 
-In the rest of this documentation about the high-level client, the `RestHighLevelClient` instance
+In the rest of this documentation about the Java High Level Client, the `RestHighLevelClient` instance
 will be referenced as `client`.
-
-Then you have access to the high level APIs such as:
-
-include::apis.asciidoc[]
-
-Each API can be executed synchronously (i.e. <<java-rest-high-document-delete,`delete`>>) or
-asynchronously (i.e. <<java-rest-high-document-delete,`deleteAsync`>>).
-The asynchronous APIs require a listener that is called on thread pool managed by the low level client
-when the response is received.