OpenSearch/docs/en/rest-api/migration/deprecation.asciidoc

[role="xpack"]
[[migration-api-deprecation]]
== Deprecation Info APIs

The deprecation API is to be used to retrieve information about different cluster, node, and index level
settings that use deprecated features that will be removed or changed in the next major version.

To see the list of offenders in your cluster, submit a GET request to the `_xpack/migration/deprecations` endpoint:

[source,js]
--------------------------------------------------
GET /_xpack/migration/deprecations
--------------------------------------------------
// CONSOLE
// TEST[skip:cannot assert tests have certain deprecations]

Example response:


["source","js",subs="attributes,callouts,macros"]
--------------------------------------------------
{
  "cluster_settings" : [
    {
      "level" : "info",
      "message" : "Network settings changes",
      "url" : "{ref-60}/breaking_60_indices_changes.html#_index_templates_use_literal_index_patterns_literal_instead_of_literal_template_literal",
      "details" : "templates using `template` field: watches,.monitoring-alerts,.watch-history-6,.ml-notifications,security-index-template,triggered_watches,.monitoring-es,.ml-meta,.ml-state,.monitoring-logstash,.ml-anomalies-,.monitoring-kibana"
    }
  ],
  "node_settings" : [ ],
  "index_settings" : {
    ".monitoring-es-6-2017.07.21" : [
      {
        "level" : "info",
        "message" : "Coercion of boolean fields",
        "url" : "{ref-60}/breaking_60_mappings_changes.html#_coercion_of_boolean_fields",
        "details" : "[[type: doc, field: spins], [type: doc, field: mlockall], [type: doc, field: node_master], [type: doc, field: primary]]"
      }
    ]
  }
}
--------------------------------------------------
// NOTCONSOLE

The response you will receive will break down all the specific forward-incompatible settings that your
cluster should resolve before upgrading. Any offending setting will be represented as a deprecation warning.

The following is an example deprecation warning:

["source","js",subs="attributes,callouts,macros"]
--------------------------------------------------
{
  "level" : "info",
  "message" : "This is the generic descriptive message of the breaking change",
  "url" : "{ref-60}/breaking_60_indices_changes.html",
  "details" : "more information, like which nodes, indices, or settings are to blame"
}
--------------------------------------------------
// NOTCONSOLE

As is shown, there is a `level` property that describes how significant the issue may be.

|=======
|none | everything is good
|info | An advisory note that something has changed. No action needed
|warning | You can upgrade directly, but you are using deprecated functionality which will not be available in the next major version
|critical | You cannot upgrade without fixing this problem
|=======

`message` and the optional `details` provide descriptive information about the deprecation warning, while the `url`
property provides a link to the Breaking Changes Documentation, where more information about this change can be found.

Any cluster-level deprecation warnings can be found under
the `cluster_settings` key. Similarly, any node-level warnings will be found under `node_settings`. 
Since only a select subset of your nodes may incorporate these settings, it is important to read the
`details` section for more information about which nodes are to be updated. Index warnings are
sectioned off per index and can be filtered using an index-pattern in the query.

Example request that only shows index-level deprecations of all `logstash-*` indices:

[source,js]
--------------------------------------------------
GET /logstash-*/_xpack/migration/deprecations
--------------------------------------------------
// CONSOLE
// TEST[skip:cannot assert tests have certain deprecations]