Совместимость REST API

Для того, чтобы помочь клиентам REST-API смягчить последствия несовместимых (разрушающих) изменений API, Elasticsearch предоставляет режим совместимости API на уровне каждого запроса, доступный по выбору.

REST API Elasticsearch в целом стабильны в разных версиях. Однако некоторые улучшения требуют изменений, несовместимых с предыдущими версиями. Например, Elasticsearch 7.x поддерживал пользовательские типы отображения во многих URL-путях, но Elasticsearch 8.0+ это не поддерживает (см. Удаление типов отображения). Указание пользовательского типа в запросе, отправленном в Elasticsearch 8.0+, возвращает ошибку. Однако, если вы запросите совместимость REST API, Elasticsearch примет запрос, даже несмотря на то, что типы отображения больше не поддерживаются.

Когда API планируется удалить или изменить несовместимым способом, исходный API устаревает на одну или несколько версий. Использование исходного API генерирует предупреждение об устаревании в логах. Это позволяет вам просмотреть логи устаревания и принять соответствующие меры до обновления. Однако в некоторых случаях сложно определить все места, где используются устаревшие API. Именно здесь может помочь совместимость REST API.

При запросе совместимости REST API Elasticsearch пытается сохранить предыдущую версию REST API. Elasticsearch пытается применить наиболее совместимый URL, тело запроса, тело ответа и параметры HTTP.

Для совместимых API это не оказывает влияния — это только касается вызовов API, которые имеют разрушающие изменения по сравнению с предыдущей версией. Ошибка все равно может быть возвращена в режиме совместимости, если Elasticsearch не может автоматически разрешить несовместимости.

Совместимость REST API должна служить мостом для плавного обновления, а не долгосрочной стратегией. Совместимость REST API поддерживается только между двумя версиями: при обработке запросов/ответов 7.x в 8.x.

При отправке запросов с использованием совместимости REST API и разрешении Elasticsearch несовместимости, сообщение записывается в журнал устаревания с категорией «compatible_api». Просмотрите журнал устаревания, чтобы определить любые пробелы в использовании и полностью поддерживаемые функции.

Дополнительную информацию о конкретных разрушающих изменениях и влиянии запроса в режим совместимости можно найти в изменениях REST API в руководстве по миграции.

Совместимость REST API реализуется на уровне каждого запроса с помощью заголовков Accept и/или Content-Type.

Например:

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

Заголовок Accept всегда требуется, а заголовок Content-Type требуется только в случае, если в запросе передается тело. Следующие значения допустимы при взаимодействии с Elasticsearch сервером версии 7.x или 8.x:

"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"

Официально поддерживаемые клиенты Elasticsearch могут включить совместимость REST API для всех запросов.

Чтобы включить совместимость REST API для всех запросов, полученных Elasticsearch, установите переменную среды ELASTIC_CLIENT_APIVERSIONING в значение true.

Для использования совместимости REST API при обновлении с 7.17 до 8.17.3: