REST API compatibility

To help REST clients mitigate the impact of non-compatible (breaking) API changes, Elasticsearch provides a per-request, opt-in API compatibility mode.

Elasticsearch REST APIs are generally stable across versions. However, some improvements require changes that are not compatible with previous versions. For example, Elasticsearch 7.x supported custom mapping types in many URL paths, but Elasticsearch 8.0+ does not (see Removal of mapping types). Specifying a custom type in a request sent to Elasticsearch 8.0+ returns an error. However, if you request REST API compatibility, Elasticsearch accepts the request even though mapping types are no longer supported.

When an API is targeted for removal or is going to be changed in a non-compatible way, the original API is deprecated for one or more releases. Using the original API triggers a deprecation warning in the logs. This enables you to review the deprecation logs and take the appropriate actions before upgrading. However, in some cases it is difficult to identify all places where deprecated APIs are being used. This is where REST API compatibility can help.

When you request REST API compatibility, Elasticsearch attempts to honor the previous REST API version. Elasticsearch attempts to apply the most compatible URL, request body, response body, and HTTP parameters.

For compatible APIs, this has no effect—​it only impacts calls to APIs that have breaking changes from the previous version. An error can still be returned in compatibility mode if Elasticsearch cannot automatically resolve the incompatibilities.

REST API compatibility should be a bridge to smooth out the upgrade process, not a long term strategy. REST API compatibility is only honored across one major version: honor 7.x requests/responses from 8.x.

When you submit requests using REST API compatibility and Elasticsearch resolves the incompatibility, a message is written to the deprecation log with the category "compatible_api". Review the deprecation log to identify any gaps in usage and fully supported features.

For information about specific breaking changes and the impact of requesting compatibility mode, see REST API changes in the migration guide.

REST API compatibility is implemented per request via the Accept and/or Content-Type headers.

For example:

Accept: "application/vnd.elasticsearch+json;compatible-with=7"
Content-Type: "application/vnd.elasticsearch+json;compatible-with=7"

The Accept header is always required and the Content-Type header is only required when a body is sent with the request. The following values are valid when communicating with a 7.x or 8.x Elasticsearch server:

"application/vnd.elasticsearch+json;compatible-with=7"
"application/vnd.elasticsearch+yaml;compatible-with=7"
"application/vnd.elasticsearch+smile;compatible-with=7"
"application/vnd.elasticsearch+cbor;compatible-with=7"

The officially supported Elasticsearch clients can enable REST API compatibility for all requests.

To enable REST API compatibility for all requests received by Elasticsearch set the environment variable ELASTIC_CLIENT_APIVERSIONING to true.

To leverage REST API compatibility during an upgrade from 7.17 to 8.15.4: