[DOCS] Reorganised common API conventions

docs/reference/api-conventions.asciidoc

@@ -1,8 +1,44 @@
-[[api-common-options]]
-= Common API Options
+[[api-conventions]]
+= API Conventions
+
+[partintro]
+--
+The *elasticsearch* REST APIs are exposed using:
+
+* <<modules-http,JSON over HTTP>>,
+* <<modules-thrift,thrift>>,
+* <<modules-memcached,memcached>>.
+
+The conventions listed in this chapter can be applied throughout the REST
+API, unless otherwise specified.
+
+* <<multi-index>>
+* <<common-options>>
+
+--
+
+[[multi-index]]
+== Multiple Indices
+
+Most APIs that refer to an `index` paramter support execution across multiple indices,
+using simple `test1,test2,test3` notation (or `_all` for all indices). It also
+support wildcards, for example: `test*`, and the ability to "add" (`+`)
+and "remove" (`-`), for example: `+test*,-test3`.
+
+All multi indices API support the `ignore_indices` option. Setting it to
+`missing` will cause indices that do not exists to be ignored from the
+execution. By default, when its not set, the request will fail.
+
+NOTE: Single index APIs such as the <<docs>> and the
+<<indices-aliases,single-index `alias` APIs>> do not support multiple indices.
+
+[[common-options]]
+== Common options
+
+The following options can be applied to all of the REST APIs.
 
 [float]
-== Pretty Results
+=== Pretty Results
 
 When appending `?pretty=true` to any request made, the JSON returned
 will be pretty formatted (use it for debugging only!). Another option is
@@ -11,7 +47,7 @@ to set `format=yaml` which will cause the result to be returned in the
 
 
 [float]
-== Human readable output
+=== Human readable output
 
 Statistics are returned in a format suitable for humans
 (eg `"exists_time": "1h"` or `"size": "1kb"`) and for computers
@@ -23,13 +59,13 @@ consumption.  The default for the `human` flag is
 `false`. added[1.00.Beta,Previously defaulted to `true`]
 
 [float]
-== Parameters
+=== Parameters
 
 Rest parameters (when using HTTP, map to HTTP URL parameters) follow the
 convention of using underscore casing.
 
 [float]
-== Boolean Values
+=== Boolean Values
 
 All REST APIs parameters (both request parameters and JSON body) support
 providing boolean "false" as the values: `false`, `0`, `no` and `off`.
@@ -37,13 +73,13 @@ All other values are considered "true". Note, this is not related to
 fields within a document indexed treated as boolean fields.
 
 [float]
-== Number Values
+=== Number Values
 
 All REST APIs support providing numbered parameters as `string` on top
 of supporting the native JSON number types.
 
 [float]
-== Result Casing
+=== Result Casing
 
 All REST APIs accept the `case` parameter. When set to `camelCase`, all
 field names in the result will be returned in camel casing, otherwise,
@@ -51,13 +87,13 @@ underscore casing will be used. Note, this does not apply to the source
 document indexed.
 
 [float]
-== JSONP
+=== JSONP
 
 All REST APIs accept a `callback` parameter resulting in a
 http://en.wikipedia.org/wiki/JSONP[JSONP] result.
 
 [float]
-== Request body in query string
+=== Request body in query string
 
 For libraries that don't accept a request body for non-POST requests,
 you can pass the request body as the `source` query string parameter

docs/reference/cluster.asciidoc

@@ -4,7 +4,7 @@
 [partintro]
 --
 ["float",id="cluster-nodes"]
-== Nodes
+== Node specification
 
 Most cluster level APIs allow to specify which nodes to execute on (for
 example, getting the node stats for a node). Nodes can be identified in
@@ -14,7 +14,7 @@ example, here are some sample executions of nodes info:
 
 [source,js]
 --------------------------------------------------
-# Local    
+# Local
 curl localhost:9200/_cluster/nodes/_local
 # Address
 curl localhost:9200/_cluster/nodes/10.0.0.3,10.0.0.4

docs/reference/docs.asciidoc

@@ -4,11 +4,22 @@
 [partintro]
 --
 
-This section describes the REST APIs *elasticsearch* provides (mainly)
-using JSON. The API is exposed using
-<<modules-http,HTTP>>,
-<<modules-thrift,thrift>>,
-<<modules-memcached,memcached>>.
+This section describes the following CRUD APIs:
+
+.Single document APIs
+* <<docs-index_>>
+* <<docs-get>>
+* <<docs-delete>>
+* <<docs-update>>
+
+.Multi-document APIs
+* <<docs-multi-get>>
+* <<docs-bulk>>
+* <<docs-bulk-udp>>
+* <<docs-delete-by-query>>
+
+NOTE: All CRUD APIs are single-index APIs. The `index` parameter accepts a single
+index name, or an `alias` which points to a single index.
 
 --
 

docs/reference/index.asciidoc

@@ -3,6 +3,8 @@
 
 include::setup.asciidoc[]
 
+include::api-conventions.asciidoc[]
+
 include::docs.asciidoc[]
 
 include::search.asciidoc[]
@@ -21,7 +23,5 @@ include::modules.asciidoc[]
 
 include::index-modules.asciidoc[]
 
-include::common-options.asciidoc[]
-
 include::glossary.asciidoc[]
 

docs/reference/search.asciidoc

@@ -3,17 +3,9 @@
 
 [partintro]
 --
-["float",id="search-multi-index"]
-== Multiple Indices
 
-All search APIs support execution across multiple indices, using simple
-`test1,test2,test3` notation (or `_all` for all indices). It also
-support wildcards, for example: `test*`, and the ability to "add" (`+`)
-and "remove" (`-`), for example: `+test*,-test3`.
-
-All multi indices API support the `ignore_indices` option. Setting it to
-`missing` will cause indices that do not exists to be ignored from the
-execution. By default, when its not set, the request will fail. 
+Most search APIs are <<search-multi-index-type,multi-index&#44; multi-type>>, with the
+exception of the <<search-explain>> and <<search-percolate>> endpoints.
 
 [float]
 [[search-routing]]

docs/reference/search/explain.asciidoc

@@ -3,7 +3,10 @@
 
 The explain api computes a score explanation for a query and a specific
 document. This can give useful feedback whether a document matches or
-didn't match a specific query. 
+didn't match a specific query.
+
+The `index` and `type` parameters expect a single index and a single
+type respectively.
 
 [float]
 === Usage
@@ -61,45 +64,45 @@ This will yield the same result as the previous request.
 [horizontal]
 `fields`::
     Allows to control which fields to return as part of the
-    document explained (support `_source` for the full document). 
+    document explained (support `_source` for the full document).
 
-`routing`:: 
+`routing`::
     Controls the routing in the case the routing was used
     during indexing.
 
-`parent`:: 
-    Same effect as setting the routing parameter. 
+`parent`::
+    Same effect as setting the routing parameter.
 
-`preference`:: 
-    Controls on which shard the explain is executed. 
+`preference`::
+    Controls on which shard the explain is executed.
 
-`source`:: 
+`source`::
     Allows the data of the request to be put in the query
-    string of the url. 
+    string of the url.
 
-`q`:: 
-    The query string (maps to the query_string query). 
+`q`::
+    The query string (maps to the query_string query).
 
-`df`:: 
+`df`::
     The default field to use when no field prefix is defined within
-    the query. Defaults to _all field. 
+    the query. Defaults to _all field.
 
-`analyzer`:: 
+`analyzer`::
     The analyzer name to be used when analyzing the query
-    string. Defaults to the analyzer of the _all field. 
+    string. Defaults to the analyzer of the _all field.
 
-`analyze_wildcard`:: 
+`analyze_wildcard`::
     Should wildcard and prefix queries be analyzed or
-    not. Defaults to false. 
+    not. Defaults to false.
 
-`lowercase_expanded_terms`:: 
+`lowercase_expanded_terms`::
     Should terms be automatically lowercased
-    or not. Defaults to true. 
+    or not. Defaults to true.
 
-`lenient`:: 
+`lenient`::
     If set to true will cause format based failures (like
-    providing text to a numeric field) to be ignored. Defaults to false. 
+    providing text to a numeric field) to be ignored. Defaults to false.
 
-`default_operator`:: 
+`default_operator`::
     The default operator to be used, can be AND or
     OR. Defaults to OR.

docs/reference/search/search.asciidoc

@@ -11,7 +11,7 @@ that match the query. The query can either be provided using a simple
 
 All search APIs can be applied across multiple types within an index, and
 across multiple indices with support for the
-<<search-multi-index,multi index syntax>>. For
+<<multi-index,multi index syntax>>. For
 example, we can search on all documents across all types within the
 twitter index: