API conventions
editAPI conventions
editThe Elasticsearch REST APIs are exposed over HTTP. Except where noted, the following conventions apply across all APIs.
Content-type requirements
editThe type of the content sent in a request body must be specified using
the Content-Type
header. The value of this header must map to one of
the supported formats that the API supports. Most APIs support JSON,
YAML, CBOR, and SMILE. The bulk and multi-search APIs support NDJSON,
JSON, and SMILE; other types will result in an error response.
When using the source
query string parameter, the content type must be
specified using the source_content_type
query string parameter.
Elasticsearch only supports UTF-8-encoded JSON. Elasticsearch ignores any other encoding headings sent with a request. Responses are also UTF-8 encoded.
X-Opaque-Id
HTTP header
editYou can pass an X-Opaque-Id
HTTP header to track the origin of a request in
Elasticsearch logs and tasks. If provided, Elasticsearch surfaces the X-Opaque-Id
value in the:
- Response of any request that includes the header
- Task management API response
- Slow logs
- Deprecation logs
For the deprecation logs, Elasticsearch also uses the X-Opaque-Id
value to throttle
and deduplicate deprecation warnings. See Deprecation logs throttling.
The X-Opaque-Id
header accepts any arbitrary value. However, we recommend you
limit these values to a finite set, such as an ID per client. Don’t generate a
unique X-Opaque-Id
header for every request. Too many unique X-Opaque-Id
values can prevent Elasticsearch from deduplicating warnings in the deprecation logs.
traceparent
HTTP header
editElasticsearch also supports a traceparent
HTTP header using the
official W3C trace
context spec. You can use the traceparent
header to trace requests across
Elastic products and other services. Because it’s only used for traces, you can
safely generate a unique traceparent
header for each request.
If provided, Elasticsearch surfaces the header’s trace-id
value as trace.id
in the:
For example, the following traceparent
value would produce the following
trade.id
value in the above logs.
`traceparent`: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 `trace.id`: 0af7651916cd43dd8448eb211c80319c
GET and POST requests
editA number of Elasticsearch GET APIs—most notably the search API—support a request body.
While the GET action makes sense in the context of retrieving information,
GET requests with a body are not supported by all HTTP libraries.
All Elasticsearch GET APIs that require a body can also be submitted as POST requests.
Alternatively, you can pass the request body as the
source
query string parameter
when using GET.
REST API version compatibility
editMajor version upgrades often include a number of breaking changes that impact how you interact with Elasticsearch. While we recommend that you monitor the deprecation logs and update applications before upgrading Elasticsearch, having to coordinate the necessary changes can be an impediment to upgrading.
You can enable an existing application to function without modification after an upgrade by including API compatibility headers, which tell Elasticsearch you are still using the previous version of the REST API. Using these headers allows the structure of requests and responses to remain the same; it does not guarantee the same behavior.
You set version compatibility on a per-request basis in the Content-Type
and Accept
headers.
Setting compatible-with
to the same major version as
the version you’re running has no impact,
but ensures that the request will still work after Elasticsearch is upgraded.
To tell Elasticsearch 8.0 you are using the 7.x request and response format,
set compatible-with=7
:
Content-Type: application/vnd.elasticsearch+json; compatible-with=7 Accept: application/vnd.elasticsearch+json; compatible-with=7