Skip to content

Latest commit

 

History

History
233 lines (185 loc) · 8.2 KB

apis-elasticsearch-conventions.asciidoc

File metadata and controls

233 lines (185 loc) · 8.2 KB

{es} API conventions

You can run {es} API requests in {dev-tools-app} → Console. For example:

GET _cat/indices?v=true

Request headers

When you call {es} APIs outside of the Console, you must provide a request header. The {es} APIs support the Authorization, Content-Type, and X-Opaque-Id headers.

Authorization

{es} APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example:

curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys for the {es} endpoint (${ES_URL}) for a project, refer to [elasticsearch-get-started].

Content-type

The type of the content sent in a request body must be specified using the Content-Type header. For example:

curl -X GET "${ES_URL}/_search?pretty" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '
  {
    "query": {
      "match_all": { "boost" : 1.2 }
    }
  }
'

The value of this header must map to one of the 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.

If you use the source query string parameter, you must specify the content type with the source_content_type query string parameter.

{es} APIs support only UTF-8-encoded JSON. Any other encoding headings sent with a request are ignored. Responses are also UTF-8 encoded.

X-Opaque-Id

You can pass an X-Opaque-Id HTTP header to track the origin of a request in {es} logs and tasks. For example:

curl -X GET "${ES_URL}/_search?pretty" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Opaque-Id: 123456" \
  -d '
  {
    "query": {
      "match_all": { "boost" : 1.2 }
    }
  }
'

{es} 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, {es} also uses the X-Opaque-Id value to throttle and deduplicate deprecation warnings.

The X-Opaque-Id header accepts any arbitrary value. However, it is recommended that 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 {es} from deduplicating warnings in the deprecation logs.

Request bodies

A number of {es} APIs with GET operations—​most notably the search API—​support a request body. While the GET operation makes sense in the context of retrieving information, GET requests with a body are not supported by all HTTP libraries.

All {es} APIs with GET operations 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. When you use this method, the source_content_type parameter should also be passed with a media type value that indicates the format of the source, such as application/json.