<commit_before>[[api-conventions]]
== API conventions

The *Elasticsearch* REST APIs are exposed using <<modules-http,JSON over HTTP>>.

The conventions listed in this chapter can be applied throughout the REST
API, unless otherwise specified.

* <<multi-index>>
* <<date-math-index-names>>
* <<cron-expressions>>
* <<common-options>>
* <<url-access-control>>

[[multi-index]]
=== Multi-target syntax

Most APIs that accept a `<data-stream>`, `<index>`, or `<target>` request path
parameter also support _multi-target syntax_.

In multi-target syntax, you can use a comma-separated list to execute a request across multiple resources, such as
data streams, indices, or index aliases: `test1,test2,test3`. You can also use
https://en.wikipedia.org/wiki/Glob_(programming)[glob-like] wildcard (`*`)
expressions to target any
resources that match the pattern: `test*` or `*test` or `te*t` or `*test*.

You can exclude targets using the `-` character: `test*,-test3`.

Multi-target APIs that can target indices support the following query
string parameters:

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]

The defaults settings for the above parameters depend on the API being used.

Some multi-target APIs that can target indices also support the following query
string parameter:

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=ignore_throttled]

NOTE: Single index APIs, such as the <<docs>> and
<<indices-aliases,single-index `alias` APIs>>, do not support multi-target
syntax.

[[date-math-index-names]]
=== Date math support in index names

Date math index name resolution enables you to search a range of time-series indices, rather
than searching all of your time-series indices and filtering the results or maintaining aliases.
Limiting the number of indices that are searched reduces the load on the cluster and improves
execution performance. For example, if you are searching for errors in your
daily logs, you can use a date math name template to restrict the search to the past
two days.

Almost all APIs that have an `index` parameter support date math in the `index` parameter
value.

A date math index name takes the following form:

[source,txt]
----------------------------------------------------------------------
<static_name{date_math_expr{date_format|time_zone}}>
----------------------------------------------------------------------

Where:

[horizontal]
`static_name`:: is the static text part of the name
`date_math_expr`:: is a dynamic date math expression that computes the date dynamically
`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
`time_zone`:: is the optional time zone. Defaults to `utc`.

NOTE: Pay attention to the usage of small vs capital letters used in the `date_format`. For example:
`mm` denotes minute of hour, while `MM` denotes month of year. Similarly `hh` denotes the hour in the
`1-12` range in combination with `AM/PM`, while `HH` denotes the hour in the `0-23` 24-hour range.

Date math expressions are resolved locale-independent. Consequently, it is not possible to use any other
calendars than the Gregorian calendar.

You must enclose date math index name expressions within angle brackets, and
all special characters should be URI encoded. For example:

[source,console]
----------------------------------------------------------------------
# GET /<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}
----------------------------------------------------------------------
// TEST[s/^/PUT logstash-2016.09.20\n/]
// TEST[s/now/2016.09.20%7C%7C/]

[NOTE]
.Percent encoding of date math characters
======================================================
The special characters used for date rounding must be URI encoded as follows:

[horizontal]
`<`:: `%3C`
`>`:: `%3E`
`/`:: `%2F`
`{`:: `%7B`
`}`:: `%7D`
`|`:: `%7C`
`+`:: `%2B`
`:`:: `%3A`
`,`:: `%2C`
======================================================

The following example shows different forms of date math index names and the final index names
they resolve to given the current time is 22nd March 2024 noon utc.

[options="header"]
|======
| Expression                                |Resolves to
| `<logstash-{now/d}>`                      | `logstash-2024.03.22`
| `<logstash-{now/M}>`                      | `logstash-2024.03.01`
| `<logstash-{now/M{yyyy.MM}}>`             | `logstash-2024.03`
| `<logstash-{now/M-1M{yyyy.MM}}>`          | `logstash-2024.02`
| `<logstash-{now/d{yyyy.MM.dd\|+12:00}}>`  | `logstash-2024.03.23`
|======<commit_msg>[DOCS] Add PUT example to `Date math in index names` (#60908)<commit_after>[[api-conventions]]
== API conventions

The *Elasticsearch* REST APIs are exposed using <<modules-http,JSON over HTTP>>.

The conventions listed in this chapter can be applied throughout the REST
API, unless otherwise specified.

* <<multi-index>>
* <<date-math-index-names>>
* <<cron-expressions>>
* <<common-options>>
* <<url-access-control>>

[[multi-index]]
=== Multi-target syntax

Most APIs that accept a `<data-stream>`, `<index>`, or `<target>` request path
parameter also support _multi-target syntax_.

In multi-target syntax, you can use a comma-separated list to execute a request across multiple resources, such as
data streams, indices, or index aliases: `test1,test2,test3`. You can also use
https://en.wikipedia.org/wiki/Glob_(programming)[glob-like] wildcard (`*`)
expressions to target any
resources that match the pattern: `test*` or `*test` or `te*t` or `*test*.

You can exclude targets using the `-` character: `test*,-test3`.

Multi-target APIs that can target indices support the following query
string parameters:

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]

The defaults settings for the above parameters depend on the API being used.

Some multi-target APIs that can target indices also support the following query
string parameter:

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=ignore_throttled]

NOTE: Single index APIs, such as the <<docs>> and
<<indices-aliases,single-index `alias` APIs>>, do not support multi-target
syntax.

[[date-math-index-names]]
=== Date math support in index names

Date math index name resolution enables you to search a range of time-series indices, rather
than searching all of your time-series indices and filtering the results or maintaining aliases.
Limiting the number of indices that are searched reduces the load on the cluster and improves
execution performance. For example, if you are searching for errors in your
daily logs, you can use a date math name template to restrict the search to the past
two days.

Almost all APIs that have an `index` parameter support date math in the `index` parameter
value.

A date math index name takes the following form:

[source,txt]
----------------------------------------------------------------------
<static_name{date_math_expr{date_format|time_zone}}>
----------------------------------------------------------------------

Where:

[horizontal]
`static_name`:: is the static text part of the name
`date_math_expr`:: is a dynamic date math expression that computes the date dynamically
`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
`time_zone`:: is the optional time zone. Defaults to `utc`.

NOTE: Pay attention to the usage of small vs capital letters used in the `date_format`. For example:
`mm` denotes minute of hour, while `MM` denotes month of year. Similarly `hh` denotes the hour in the
`1-12` range in combination with `AM/PM`, while `HH` denotes the hour in the `0-23` 24-hour range.

Date math expressions are resolved locale-independent. Consequently, it is not possible to use any other
calendars than the Gregorian calendar.

You must enclose date math index name expressions within angle brackets, and
all special characters should be URI encoded. For example:

[source,console]
----
# PUT /<my-index-{now/d}>
PUT /%3Cmy-index-%7Bnow%2Fd%7D%3E
----

[NOTE]
.Percent encoding of date math characters
======================================================
The special characters used for date rounding must be URI encoded as follows:

[horizontal]
`<`:: `%3C`
`>`:: `%3E`
`/`:: `%2F`
`{`:: `%7B`
`}`:: `%7D`
`|`:: `%7C`
`+`:: `%2B`
`:`:: `%3A`
`,`:: `%2C`
======================================================

The following example shows different forms of date math index names and the final index names
they resolve to given the current time is 22nd March 2024 noon utc.

[options="header"]
|======
| Expression                                |Resolves to
| `<logstash-{now/d}>`                      | `logstash-2024.03.22`
| `<logstash-{now/M}>`                      | `logstash-2024.03.01`
| `<logstash-{now/M{yyyy.MM}}>`             | `logstash-2024.03`
| `<logstash-{now/M-1M{yyyy.MM}}>`          | `logstash-2024.02`
| `<logstash-{now/d{yyyy.MM.dd\|+12:00}}>`  | `logstash-2024.03.23`
|======
{'fraction_non_alphanumeric': 0.18314828266057903, 'fraction_numerical': 0.017744111237937118, 'mean_word_length': 3.5440829797265443, 'pattern_counts': {'":': 2, '<': 57, '<?xml version=': 0, '>': 57, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4426441', 'n_tokens_mistral': 2971, 'n_tokens_neox': 2791, 'n_words': 1023}