api-conventions.asciidoc 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682
  1. [[api-conventions]]
  2. == API conventions
  3. The *Elasticsearch* REST APIs are exposed using <<modules-http,JSON over HTTP>>.
  4. The conventions listed in this chapter can be applied throughout the REST
  5. API, unless otherwise specified.
  6. * <<multi-index>>
  7. * <<date-math-index-names>>
  8. * <<cron-expressions>>
  9. * <<common-options>>
  10. * <<url-access-control>>
  11. [[multi-index]]
  12. === Multi-target syntax
  13. Most APIs that accept a `<data-stream>`, `<index>`, or `<target>` request path
  14. parameter also support _multi-target syntax_.
  15. In multi-target syntax, you can use a comma-separated list to execute a request across multiple resources, such as
  16. data streams, indices, or index aliases: `test1,test2,test3`. You can also use
  17. https://en.wikipedia.org/wiki/Glob_(programming)[glob-like] wildcard (`*`)
  18. expressions to target any
  19. resources that match the pattern: `test*` or `*test` or `te*t` or `*test*.
  20. You can exclude targets using the `-` character: `test*,-test3`.
  21. Multi-target APIs that can target indices support the following query
  22. string parameters:
  23. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
  24. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
  25. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
  26. The defaults settings for the above parameters depend on the API being used.
  27. Some multi-target APIs that can target indices also support the following query
  28. string parameter:
  29. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=ignore_throttled]
  30. NOTE: Single index APIs, such as the <<docs>> and
  31. <<indices-aliases,single-index `alias` APIs>>, do not support multi-target
  32. syntax.
  33. [[date-math-index-names]]
  34. === Date math support in index names
  35. Date math index name resolution enables you to search a range of time-series indices, rather
  36. than searching all of your time-series indices and filtering the results or maintaining aliases.
  37. Limiting the number of indices that are searched reduces the load on the cluster and improves
  38. execution performance. For example, if you are searching for errors in your
  39. daily logs, you can use a date math name template to restrict the search to the past
  40. two days.
  41. Almost all APIs that have an `index` parameter support date math in the `index` parameter
  42. value.
  43. A date math index name takes the following form:
  44. [source,txt]
  45. ----------------------------------------------------------------------
  46. <static_name{date_math_expr{date_format|time_zone}}>
  47. ----------------------------------------------------------------------
  48. Where:
  49. [horizontal]
  50. `static_name`:: is the static text part of the name
  51. `date_math_expr`:: is a dynamic date math expression that computes the date dynamically
  52. `date_format`:: is the optional format in which the computed date should be rendered. Defaults to `yyyy.MM.dd`. Format should be compatible with java-time https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html
  53. `time_zone`:: is the optional time zone. Defaults to `utc`.
  54. NOTE: Pay attention to the usage of small vs capital letters used in the `date_format`. For example:
  55. `mm` denotes minute of hour, while `MM` denotes month of year. Similarly `hh` denotes the hour in the
  56. `1-12` range in combination with `AM/PM`, while `HH` denotes the hour in the `0-23` 24-hour range.
  57. Date math expressions are resolved locale-independent. Consequently, it is not possible to use any other
  58. calendars than the Gregorian calendar.
  59. You must enclose date math index name expressions within angle brackets, and
  60. all special characters should be URI encoded. For example:
  61. [source,console]
  62. ----------------------------------------------------------------------
  63. # GET /<logstash-{now/d}>/_search
  64. GET /%3Clogstash-%7Bnow%2Fd%7D%3E/_search
  65. {
  66. "query" : {
  67. "match": {
  68. "test": "data"
  69. }
  70. }
  71. }
  72. ----------------------------------------------------------------------
  73. // TEST[s/^/PUT logstash-2016.09.20\n/]
  74. // TEST[s/now/2016.09.20%7C%7C/]
  75. [NOTE]
  76. .Percent encoding of date math characters
  77. ======================================================
  78. The special characters used for date rounding must be URI encoded as follows:
  79. [horizontal]
  80. `<`:: `%3C`
  81. `>`:: `%3E`
  82. `/`:: `%2F`
  83. `{`:: `%7B`
  84. `}`:: `%7D`
  85. `|`:: `%7C`
  86. `+`:: `%2B`
  87. `:`:: `%3A`
  88. `,`:: `%2C`
  89. ======================================================
  90. The following example shows different forms of date math index names and the final index names
  91. they resolve to given the current time is 22nd March 2024 noon utc.
  92. [options="header"]
  93. |======
  94. | Expression |Resolves to
  95. | `<logstash-{now/d}>` | `logstash-2024.03.22`
  96. | `<logstash-{now/M}>` | `logstash-2024.03.01`
  97. | `<logstash-{now/M{yyyy.MM}}>` | `logstash-2024.03`
  98. | `<logstash-{now/M-1M{yyyy.MM}}>` | `logstash-2024.02`
  99. | `<logstash-{now/d{yyyy.MM.dd\|+12:00}}>` | `logstash-2024.03.23`
  100. |======
  101. To use the characters `{` and `}` in the static part of an index name template, escape them
  102. with a backslash `\`, for example:
  103. * `<elastic\\{ON\\}-{now/M}>` resolves to `elastic{ON}-2024.03.01`
  104. The following example shows a search request that searches the Logstash indices for the past
  105. three days, assuming the indices use the default Logstash index name format,
  106. `logstash-YYYY.MM.dd`.
  107. [source,console]
  108. ----------------------------------------------------------------------
  109. # GET /<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>/_search
  110. GET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search
  111. {
  112. "query" : {
  113. "match": {
  114. "test": "data"
  115. }
  116. }
  117. }
  118. ----------------------------------------------------------------------
  119. // TEST[s/^/PUT logstash-2016.09.20\nPUT logstash-2016.09.19\nPUT logstash-2016.09.18\n/]
  120. // TEST[s/now/2016.09.20%7C%7C/]
  121. include::rest-api/cron-expressions.asciidoc[]
  122. [[common-options]]
  123. === Common options
  124. The following options can be applied to all of the REST APIs.
  125. [discrete]
  126. ==== Pretty Results
  127. When appending `?pretty=true` to any request made, the JSON returned
  128. will be pretty formatted (use it for debugging only!). Another option is
  129. to set `?format=yaml` which will cause the result to be returned in the
  130. (sometimes) more readable yaml format.
  131. [discrete]
  132. ==== Human readable output
  133. Statistics are returned in a format suitable for humans
  134. (e.g. `"exists_time": "1h"` or `"size": "1kb"`) and for computers
  135. (e.g. `"exists_time_in_millis": 3600000` or `"size_in_bytes": 1024`).
  136. The human readable values can be turned off by adding `?human=false`
  137. to the query string. This makes sense when the stats results are
  138. being consumed by a monitoring tool, rather than intended for human
  139. consumption. The default for the `human` flag is
  140. `false`.
  141. [[date-math]]
  142. [discrete]
  143. ==== Date Math
  144. Most parameters which accept a formatted date value -- such as `gt` and `lt`
  145. in <<query-dsl-range-query,`range` queries>>, or `from` and `to`
  146. in <<search-aggregations-bucket-daterange-aggregation,`daterange`
  147. aggregations>> -- understand date maths.
  148. The expression starts with an anchor date, which can either be `now`, or a
  149. date string ending with `||`. This anchor date can optionally be followed by
  150. one or more maths expressions:
  151. * `+1h`: Add one hour
  152. * `-1d`: Subtract one day
  153. * `/d`: Round down to the nearest day
  154. The supported time units differ from those supported by <<time-units, time units>> for durations.
  155. The supported units are:
  156. [horizontal]
  157. `y`:: Years
  158. `M`:: Months
  159. `w`:: Weeks
  160. `d`:: Days
  161. `h`:: Hours
  162. `H`:: Hours
  163. `m`:: Minutes
  164. `s`:: Seconds
  165. Assuming `now` is `2001-01-01 12:00:00`, some examples are:
  166. [horizontal]
  167. `now+1h`:: `now` in milliseconds plus one hour. Resolves to: `2001-01-01 13:00:00`
  168. `now-1h`:: `now` in milliseconds minus one hour. Resolves to: `2001-01-01 11:00:00`
  169. `now-1h/d`:: `now` in milliseconds minus one hour, rounded down to UTC 00:00. Resolves to: `2001-01-01 00:00:00`
  170. `2001.02.01\|\|+1M/d`:: `2001-02-01` in milliseconds plus one month. Resolves to: `2001-03-01 00:00:00`
  171. [discrete]
  172. [[common-options-response-filtering]]
  173. ==== Response Filtering
  174. All REST APIs accept a `filter_path` parameter that can be used to reduce
  175. the response returned by Elasticsearch. This parameter takes a comma
  176. separated list of filters expressed with the dot notation:
  177. [source,console]
  178. --------------------------------------------------
  179. GET /_search?q=kimchy&filter_path=took,hits.hits._id,hits.hits._score
  180. --------------------------------------------------
  181. // TEST[setup:my_index]
  182. Responds:
  183. [source,console-result]
  184. --------------------------------------------------
  185. {
  186. "took" : 3,
  187. "hits" : {
  188. "hits" : [
  189. {
  190. "_id" : "0",
  191. "_score" : 1.6375021
  192. }
  193. ]
  194. }
  195. }
  196. --------------------------------------------------
  197. // TESTRESPONSE[s/"took" : 3/"took" : $body.took/]
  198. // TESTRESPONSE[s/1.6375021/$body.hits.hits.0._score/]
  199. It also supports the `*` wildcard character to match any field or part
  200. of a field's name:
  201. [source,console]
  202. --------------------------------------------------
  203. GET /_cluster/state?filter_path=metadata.indices.*.stat*
  204. --------------------------------------------------
  205. // TEST[s/^/PUT my-index-000001\n/]
  206. Responds:
  207. [source,console-result]
  208. --------------------------------------------------
  209. {
  210. "metadata" : {
  211. "indices" : {
  212. "my-index-000001": {"state": "open"}
  213. }
  214. }
  215. }
  216. --------------------------------------------------
  217. And the `**` wildcard can be used to include fields without knowing the
  218. exact path of the field. For example, we can return the Lucene version
  219. of every segment with this request:
  220. [source,console]
  221. --------------------------------------------------
  222. GET /_cluster/state?filter_path=routing_table.indices.**.state
  223. --------------------------------------------------
  224. // TEST[s/^/PUT my-index-000001\n/]
  225. Responds:
  226. [source,console-result]
  227. --------------------------------------------------
  228. {
  229. "routing_table": {
  230. "indices": {
  231. "my-index-000001": {
  232. "shards": {
  233. "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]
  234. }
  235. }
  236. }
  237. }
  238. }
  239. --------------------------------------------------
  240. It is also possible to exclude one or more fields by prefixing the filter with the char `-`:
  241. [source,console]
  242. --------------------------------------------------
  243. GET /_count?filter_path=-_shards
  244. --------------------------------------------------
  245. // TEST[setup:my_index]
  246. Responds:
  247. [source,console-result]
  248. --------------------------------------------------
  249. {
  250. "count" : 5
  251. }
  252. --------------------------------------------------
  253. And for more control, both inclusive and exclusive filters can be combined in the same expression. In
  254. this case, the exclusive filters will be applied first and the result will be filtered again using the
  255. inclusive filters:
  256. [source,console]
  257. --------------------------------------------------
  258. GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*
  259. --------------------------------------------------
  260. // TEST[s/^/PUT my-index-000001\nPUT my-index-000002\nPUT my-index-000003\nPUT logstash-2016.01\n/]
  261. Responds:
  262. [source,console-result]
  263. --------------------------------------------------
  264. {
  265. "metadata" : {
  266. "indices" : {
  267. "my-index-000001" : {"state" : "open"},
  268. "my-index-000002" : {"state" : "open"},
  269. "my-index-000003" : {"state" : "open"}
  270. }
  271. }
  272. }
  273. --------------------------------------------------
  274. Note that Elasticsearch sometimes returns directly the raw value of a field,
  275. like the `_source` field. If you want to filter `_source` fields, you should
  276. consider combining the already existing `_source` parameter (see
  277. <<get-source-filtering,Get API>> for more details) with the `filter_path`
  278. parameter like this:
  279. [source,console]
  280. --------------------------------------------------
  281. POST /library/_doc?refresh
  282. {"title": "Book #1", "rating": 200.1}
  283. POST /library/_doc?refresh
  284. {"title": "Book #2", "rating": 1.7}
  285. POST /library/_doc?refresh
  286. {"title": "Book #3", "rating": 0.1}
  287. GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc
  288. --------------------------------------------------
  289. [source,console-result]
  290. --------------------------------------------------
  291. {
  292. "hits" : {
  293. "hits" : [ {
  294. "_source":{"title":"Book #1"}
  295. }, {
  296. "_source":{"title":"Book #2"}
  297. }, {
  298. "_source":{"title":"Book #3"}
  299. } ]
  300. }
  301. }
  302. --------------------------------------------------
  303. [discrete]
  304. ==== Flat Settings
  305. The `flat_settings` flag affects rendering of the lists of settings. When the
  306. `flat_settings` flag is `true`, settings are returned in a flat format:
  307. [source,console]
  308. --------------------------------------------------
  309. GET my-index-000001/_settings?flat_settings=true
  310. --------------------------------------------------
  311. // TEST[setup:my_index]
  312. Returns:
  313. [source,console-result]
  314. --------------------------------------------------
  315. {
  316. "my-index-000001" : {
  317. "settings": {
  318. "index.number_of_replicas": "1",
  319. "index.number_of_shards": "1",
  320. "index.creation_date": "1474389951325",
  321. "index.uuid": "n6gzFZTgS664GUfx0Xrpjw",
  322. "index.version.created": ...,
  323. "index.provided_name" : "my-index-000001"
  324. }
  325. }
  326. }
  327. --------------------------------------------------
  328. // TESTRESPONSE[s/1474389951325/$body.my-index-000001.settings.index\\\\.creation_date/]
  329. // TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.my-index-000001.settings.index\\\\.uuid/]
  330. // TESTRESPONSE[s/"index.version.created": \.\.\./"index.version.created": $body.my-index-000001.settings.index\\\\.version\\\\.created/]
  331. When the `flat_settings` flag is `false`, settings are returned in a more
  332. human readable structured format:
  333. [source,console]
  334. --------------------------------------------------
  335. GET my-index-000001/_settings?flat_settings=false
  336. --------------------------------------------------
  337. // TEST[setup:my_index]
  338. Returns:
  339. [source,console-result]
  340. --------------------------------------------------
  341. {
  342. "my-index-000001" : {
  343. "settings" : {
  344. "index" : {
  345. "number_of_replicas": "1",
  346. "number_of_shards": "1",
  347. "creation_date": "1474389951325",
  348. "uuid": "n6gzFZTgS664GUfx0Xrpjw",
  349. "version": {
  350. "created": ...
  351. },
  352. "provided_name" : "my-index-000001"
  353. }
  354. }
  355. }
  356. }
  357. --------------------------------------------------
  358. // TESTRESPONSE[s/1474389951325/$body.my-index-000001.settings.index.creation_date/]
  359. // TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.my-index-000001.settings.index.uuid/]
  360. // TESTRESPONSE[s/"created": \.\.\./"created": $body.my-index-000001.settings.index.version.created/]
  361. By default `flat_settings` is set to `false`.
  362. [discrete]
  363. ==== Parameters
  364. Rest parameters (when using HTTP, map to HTTP URL parameters) follow the
  365. convention of using underscore casing.
  366. [discrete]
  367. ==== Boolean Values
  368. All REST API parameters (both request parameters and JSON body) support
  369. providing boolean "false" as the value `false` and boolean "true" as the
  370. value `true`. All other values will raise an error.
  371. [discrete]
  372. ==== Number Values
  373. All REST APIs support providing numbered parameters as `string` on top
  374. of supporting the native JSON number types.
  375. [[time-units]]
  376. [discrete]
  377. ==== Time units
  378. Whenever durations need to be specified, e.g. for a `timeout` parameter, the duration must specify
  379. the unit, like `2d` for 2 days. The supported units are:
  380. [horizontal]
  381. `d`:: Days
  382. `h`:: Hours
  383. `m`:: Minutes
  384. `s`:: Seconds
  385. `ms`:: Milliseconds
  386. `micros`:: Microseconds
  387. `nanos`:: Nanoseconds
  388. [[byte-units]]
  389. [discrete]
  390. ==== Byte size units
  391. Whenever the byte size of data needs to be specified, e.g. when setting a buffer size
  392. parameter, the value must specify the unit, like `10kb` for 10 kilobytes. Note that
  393. these units use powers of 1024, so `1kb` means 1024 bytes. The supported units are:
  394. [horizontal]
  395. `b`:: Bytes
  396. `kb`:: Kilobytes
  397. `mb`:: Megabytes
  398. `gb`:: Gigabytes
  399. `tb`:: Terabytes
  400. `pb`:: Petabytes
  401. [[size-units]]
  402. [discrete]
  403. ==== Unit-less quantities
  404. Unit-less quantities means that they don't have a "unit" like "bytes" or "Hertz" or "meter" or "long tonne".
  405. If one of these quantities is large we'll print it out like 10m for 10,000,000 or 7k for 7,000. We'll still print 87
  406. when we mean 87 though. These are the supported multipliers:
  407. [horizontal]
  408. `k`:: Kilo
  409. `m`:: Mega
  410. `g`:: Giga
  411. `t`:: Tera
  412. `p`:: Peta
  413. [[distance-units]]
  414. [discrete]
  415. ==== Distance Units
  416. Wherever distances need to be specified, such as the `distance` parameter in
  417. the <<query-dsl-geo-distance-query>>), the default unit is meters if none is specified.
  418. Distances can be specified in other units, such as `"1km"` or
  419. `"2mi"` (2 miles).
  420. The full list of units is listed below:
  421. [horizontal]
  422. Mile:: `mi` or `miles`
  423. Yard:: `yd` or `yards`
  424. Feet:: `ft` or `feet`
  425. Inch:: `in` or `inch`
  426. Kilometer:: `km` or `kilometers`
  427. Meter:: `m` or `meters`
  428. Centimeter:: `cm` or `centimeters`
  429. Millimeter:: `mm` or `millimeters`
  430. Nautical mile:: `NM`, `nmi`, or `nauticalmiles`
  431. [[fuzziness]]
  432. [discrete]
  433. ==== Fuzziness
  434. Some queries and APIs support parameters to allow inexact _fuzzy_ matching,
  435. using the `fuzziness` parameter.
  436. When querying `text` or `keyword` fields, `fuzziness` is interpreted as a
  437. {wikipedia}/Levenshtein_distance[Levenshtein Edit Distance]
  438. -- the number of one character changes that need to be made to one string to
  439. make it the same as another string.
  440. The `fuzziness` parameter can be specified as:
  441. [horizontal]
  442. `0`, `1`, `2`::
  443. The maximum allowed Levenshtein Edit Distance (or number of edits)
  444. `AUTO`::
  445. +
  446. --
  447. Generates an edit distance based on the length of the term.
  448. Low and high distance arguments may be optionally provided `AUTO:[low],[high]`. If not specified,
  449. the default values are 3 and 6, equivalent to `AUTO:3,6` that make for lengths:
  450. `0..2`:: Must match exactly
  451. `3..5`:: One edit allowed
  452. `>5`:: Two edits allowed
  453. `AUTO` should generally be the preferred value for `fuzziness`.
  454. --
  455. [discrete]
  456. [[common-options-error-options]]
  457. ==== Enabling stack traces
  458. By default when a request returns an error Elasticsearch doesn't include the
  459. stack trace of the error. You can enable that behavior by setting the
  460. `error_trace` url parameter to `true`. For example, by default when you send an
  461. invalid `size` parameter to the `_search` API:
  462. [source,console]
  463. ----------------------------------------------------------------------
  464. POST /my-index-000001/_search?size=surprise_me
  465. ----------------------------------------------------------------------
  466. // TEST[s/surprise_me/surprise_me&error_trace=false/ catch:bad_request]
  467. // Since the test system sends error_trace=true by default we have to override
  468. The response looks like:
  469. [source,console-result]
  470. ----------------------------------------------------------------------
  471. {
  472. "error" : {
  473. "root_cause" : [
  474. {
  475. "type" : "illegal_argument_exception",
  476. "reason" : "Failed to parse int parameter [size] with value [surprise_me]"
  477. }
  478. ],
  479. "type" : "illegal_argument_exception",
  480. "reason" : "Failed to parse int parameter [size] with value [surprise_me]",
  481. "caused_by" : {
  482. "type" : "number_format_exception",
  483. "reason" : "For input string: \"surprise_me\""
  484. }
  485. },
  486. "status" : 400
  487. }
  488. ----------------------------------------------------------------------
  489. But if you set `error_trace=true`:
  490. [source,console]
  491. ----------------------------------------------------------------------
  492. POST /my-index-000001/_search?size=surprise_me&error_trace=true
  493. ----------------------------------------------------------------------
  494. // TEST[catch:bad_request]
  495. The response looks like:
  496. [source,console-result]
  497. ----------------------------------------------------------------------
  498. {
  499. "error": {
  500. "root_cause": [
  501. {
  502. "type": "illegal_argument_exception",
  503. "reason": "Failed to parse int parameter [size] with value [surprise_me]",
  504. "stack_trace": "Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException..."
  505. }
  506. ],
  507. "type": "illegal_argument_exception",
  508. "reason": "Failed to parse int parameter [size] with value [surprise_me]",
  509. "stack_trace": "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]\n at org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:175)...",
  510. "caused_by": {
  511. "type": "number_format_exception",
  512. "reason": "For input string: \"surprise_me\"",
  513. "stack_trace": "java.lang.NumberFormatException: For input string: \"surprise_me\"\n at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..."
  514. }
  515. },
  516. "status": 400
  517. }
  518. ----------------------------------------------------------------------
  519. // TESTRESPONSE[s/"stack_trace": "Failed to parse int parameter.+\.\.\."/"stack_trace": $body.error.root_cause.0.stack_trace/]
  520. // TESTRESPONSE[s/"stack_trace": "java.lang.IllegalArgum.+\.\.\."/"stack_trace": $body.error.stack_trace/]
  521. // TESTRESPONSE[s/"stack_trace": "java.lang.Number.+\.\.\."/"stack_trace": $body.error.caused_by.stack_trace/]
  522. [discrete]
  523. ==== Request body in query string
  524. For libraries that don't accept a request body for non-POST requests,
  525. you can pass the request body as the `source` query string parameter
  526. instead. When using this method, the `source_content_type` parameter
  527. should also be passed with a media type value that indicates the format
  528. of the source, such as `application/json`.
  529. [discrete]
  530. ==== Content-Type Requirements
  531. The type of the content sent in a request body must be specified using
  532. the `Content-Type` header. The value of this header must map to one of
  533. the supported formats that the API supports. Most APIs support JSON,
  534. YAML, CBOR, and SMILE. The bulk and multi-search APIs support NDJSON,
  535. JSON, and SMILE; other types will result in an error response.
  536. Additionally, when using the `source` query string parameter, the
  537. content type must be specified using the `source_content_type` query
  538. string parameter.
  539. [[url-access-control]]
  540. === URL-based access control
  541. Many users use a proxy with URL-based access control to secure access to
  542. {es} data streams and indices. For <<search-multi-search,multi-search>>,
  543. <<docs-multi-get,multi-get>>, and <<docs-bulk,bulk>> requests, the user has
  544. the choice of specifying a data stream or index in the URL and on each individual request
  545. within the request body. This can make URL-based access control challenging.
  546. To prevent the user from overriding the data stream or index specified in the
  547. URL, set `rest.action.multi.allow_explicit_index` to `false` in `elasticsearch.yml`.
  548. This causes {es} to
  549. reject requests that explicitly specfiy a data stream or index in the request body.