From ce584b3211f216b2a704c4016fe6db72e5f79fe3 Mon Sep 17 00:00:00 2001
From: Tomas Della Vedova <delvedor@users.noreply.github.com>
Date: Mon, 16 Sep 2019 17:41:36 +0200
Subject: [PATCH] Updated API reference doc (#945)

* Updated API reference doc

* Updated docs script
---
 docs/reference.asciidoc       | 36 +++++++++++++++++++++++++++++++++++
 scripts/utils/generateDocs.js | 36 +++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/docs/reference.asciidoc b/docs/reference.asciidoc
index b62327cbe..dcc00ee50 100644
--- a/docs/reference.asciidoc
+++ b/docs/reference.asciidoc
@@ -1,6 +1,42 @@
 [[api-reference]]
 == API Reference
 
+This document contains the entire list of the Elasticsearch API supported by the client, both OSS and commercial. The client is entirely licensed under Apache 2.0.
+
+Elasticsearch exposes an HTTP layer to communicate with, and the client is a library that will help you do this. Because of this reason, you will see HTTP related parameters, such as `body` or `headers`.
+
+Every API can accept two objects, the first contains all the parameters that will be sent to Elasticsearch, while the second includes the request specific parameters, such as timeouts, headers, and so on.
+In the first object, every parameter but the body will be sent via querystring or url parameter, depending on the API, and every unrecognized parameter will be sent as querystring.
+
+[source,js]
+----
+// promise API
+const result = await client.search({
+  index: 'my-index',
+  from: 20,
+  size: 10,
+  body: { foo: 'bar' }
+}, {
+  ignore: [404],
+  maxRetries: 3
+})
+
+// calback API
+client.search({
+  index: 'my-index',
+  from: 20,
+  size: 10,
+  body: { foo: 'bar' }
+}, {
+  ignore: [404],
+  maxRetries: 3
+}, (err, result) => {
+  if (err) console.log(err)
+})
+----
+
+In this document, you will find the reference of every parameter accepted by the querystring or the url. If you also need to send the body, you can find the documentation of its format in the reference link that is present along with every endpoint.
+
 ////////
 
 This documentation is generated by running:
diff --git a/scripts/utils/generateDocs.js b/scripts/utils/generateDocs.js
index f881998cf..d49f225e7 100644
--- a/scripts/utils/generateDocs.js
+++ b/scripts/utils/generateDocs.js
@@ -11,6 +11,42 @@ function generateDocs (common, spec) {
   [[api-reference]]
   == API Reference
 
+  This document contains the entire list of the Elasticsearch API supported by the client, both OSS and commercial. The client is entirely licensed under Apache 2.0.
+
+  Elasticsearch exposes an HTTP layer to communicate with, and the client is a library that will help you do this. Because of this reason, you will see HTTP related parameters, such as ${'`'}body${'`'} or ${'`'}headers${'`'}.
+
+  Every API can accept two objects, the first contains all the parameters that will be sent to Elasticsearch, while the second includes the request specific parameters, such as timeouts, headers, and so on.
+  In the first object, every parameter but the body will be sent via querystring or url parameter, depending on the API, and every unrecognized parameter will be sent as querystring.
+
+  [source,js]
+  ----
+  // promise API
+  const result = await client.search({
+    index: 'my-index',
+    from: 20,
+    size: 10,
+    body: { foo: 'bar' }
+  }, {
+    ignore: [404],
+    maxRetries: 3
+  })
+
+  // calback API
+  client.search({
+    index: 'my-index',
+    from: 20,
+    size: 10,
+    body: { foo: 'bar' }
+  }, {
+    ignore: [404],
+    maxRetries: 3
+  }, (err, result) => {
+    if (err) console.log(err)
+  })
+  ----
+
+  In this document, you will find the reference of every parameter accepted by the querystring or the url. If you also need to send the body, you can find the documentation of its format in the reference link that is present along with every endpoint.
+
   ////////
 
   This documentation is generated by running: