From 9a062e465ce86aa9a72dd6dd5337be6447a83506 Mon Sep 17 00:00:00 2001 From: Clinton Gormley Date: Sun, 13 Oct 2013 16:46:56 +0200 Subject: [PATCH] [DOCS] Reorganised common API conventions --- ...ions.asciidoc => api-conventions.asciidoc} | 56 +++++++++++++++---- docs/reference/cluster.asciidoc | 4 +- docs/reference/docs.asciidoc | 21 +++++-- docs/reference/index.asciidoc | 4 +- docs/reference/search.asciidoc | 12 +--- docs/reference/search/explain.asciidoc | 47 ++++++++-------- docs/reference/search/search.asciidoc | 2 +- 7 files changed, 94 insertions(+), 52 deletions(-) rename docs/reference/{common-options.asciidoc => api-conventions.asciidoc} (58%) diff --git a/docs/reference/common-options.asciidoc b/docs/reference/api-conventions.asciidoc similarity index 58% rename from docs/reference/common-options.asciidoc rename to docs/reference/api-conventions.asciidoc index ad5e27405ba..0def8e20287 100644 --- a/docs/reference/common-options.asciidoc +++ b/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: + +* <>, +* <>, +* <>. + +The conventions listed in this chapter can be applied throughout the REST +API, unless otherwise specified. + +* <> +* <> + +-- + +[[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 <> and the +<> 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 diff --git a/docs/reference/cluster.asciidoc b/docs/reference/cluster.asciidoc index b14fb654a7a..60971a5853b 100644 --- a/docs/reference/cluster.asciidoc +++ b/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 diff --git a/docs/reference/docs.asciidoc b/docs/reference/docs.asciidoc index 754019ddeb6..7526abc5fb6 100644 --- a/docs/reference/docs.asciidoc +++ b/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 -<>, -<>, -<>. +This section describes the following CRUD APIs: + +.Single document APIs +* <> +* <> +* <> +* <> + +.Multi-document APIs +* <> +* <> +* <> +* <> + +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. -- diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc index fc95e32c774..307de6487c6 100644 --- a/docs/reference/index.asciidoc +++ b/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[] diff --git a/docs/reference/search.asciidoc b/docs/reference/search.asciidoc index bbf12d36389..fd3b06d3119 100644 --- a/docs/reference/search.asciidoc +++ b/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 <>, with the +exception of the <> and <> endpoints. [float] [[search-routing]] diff --git a/docs/reference/search/explain.asciidoc b/docs/reference/search/explain.asciidoc index 8b68c74c71b..fb346d01962 100644 --- a/docs/reference/search/explain.asciidoc +++ b/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. diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc index 745b1cf554a..5483c194a23 100644 --- a/docs/reference/search/search.asciidoc +++ b/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 -<>. For +<>. For example, we can search on all documents across all types within the twitter index: