140 lines
4.4 KiB
Plaintext
140 lines
4.4 KiB
Plaintext
[[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` parameter 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 it's 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
|
|
|
|
When appending `?pretty=true` to any request made, the JSON returned
|
|
will be pretty formatted (use it for debugging only!). Another option is
|
|
to set `format=yaml` which will cause the result to be returned in the
|
|
(sometimes) more readable yaml format.
|
|
|
|
|
|
[float]
|
|
=== Human readable output
|
|
|
|
Statistics are returned in a format suitable for humans
|
|
(eg `"exists_time": "1h"` or `"size": "1kb"`) and for computers
|
|
(eg `"exists_time_in_millis": 3600000`` or `"size_in_bytes": 1024`).
|
|
The human readable values can be turned off by adding `?human=false`
|
|
to the query string. This makes sense when the stats results are
|
|
being consumed by a monitoring tool, rather than intended for human
|
|
consumption. The default for the `human` flag is
|
|
`false`. added[1.00.Beta,Previously defaulted to `true`]
|
|
|
|
[float]
|
|
=== Parameters
|
|
|
|
Rest parameters (when using HTTP, map to HTTP URL parameters) follow the
|
|
convention of using underscore casing.
|
|
|
|
[float]
|
|
=== Boolean Values
|
|
|
|
All REST APIs parameters (both request parameters and JSON body) support
|
|
providing boolean "false" as the values: `false`, `0`, `no` and `off`.
|
|
All other values are considered "true". Note, this is not related to
|
|
fields within a document indexed treated as boolean fields.
|
|
|
|
[float]
|
|
=== Number Values
|
|
|
|
All REST APIs support providing numbered parameters as `string` on top
|
|
of supporting the native JSON number types.
|
|
|
|
[[distance-units]]
|
|
[float]
|
|
=== Distance Units
|
|
|
|
Wherever distances need to be specified, such as the `distance` parameter in
|
|
the <<query-dsl-geo-distance-filter>>) or the `precision` parameter in the
|
|
<<query-dsl-geohash-cell-filter>>, the default unit if none is specified is
|
|
the meter. Distances can be specified in other units, such as `"1km"` or
|
|
`"2mi"` (2 miles).
|
|
|
|
The full list of units is listed below:
|
|
|
|
[horizontal]
|
|
Mile:: `mi` or `miles`
|
|
Yard:: `yd` or `yards`
|
|
Inch:: `in` or `inch`
|
|
Kilometer:: `km` or `kilometers`
|
|
Meter:: `m` or `meters`
|
|
Centimeter:: `cm` or `centimeters`
|
|
Millimeter:: `mm` or `millimeters`
|
|
|
|
|
|
[float]
|
|
=== 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,
|
|
underscore casing will be used. Note, this does not apply to the source
|
|
document indexed.
|
|
|
|
[float]
|
|
=== 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
|
|
|
|
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
|
|
instead.
|
|
|
|
[[url-access-control]]
|
|
== URL-based access control
|
|
|
|
Many users use a proxy with URL-based access control to secure access to
|
|
Elasticsearch indices. For <<search-multi-search,multi-search>>,
|
|
<<docs-multi-get,multi-get>> and <<docs-bulk,bulk>> requests, the user has
|
|
the choice of specifying an index in the URL and on each individual request
|
|
within the request body. This can make URL-based access control challenging.
|
|
|
|
To prevent the user from overriding the index which has been specified in the
|
|
URL, add this setting to the `config.yml` file:
|
|
|
|
rest.action.multi.allow_explicit_index: false
|
|
|
|
The default value is `true`, but when set to `false`, Elasticsearch will
|
|
reject requests that have an explicit index specified in the request body.
|