[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

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

@@ -5,6 +5,9 @@ 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.
 
+The `index` and `type` parameters expect a single index and a single
+type respectively.
+
 [float]
 === Usage
 

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: