API Deprecations replace deprecated: true with the deprecated object

[Bamieh]

The following routes have deprecated: true. We need to replace them with the deprecated object that provides enough metadata for users in UA to be able to address it before their next upgrade.
We will start throwing an error in the near future to prevent developers from passing true to the deprecated param so we need to address those ASAP.

Here is an example of what true needs to be replaced with (note the options.deprecated param):

  router.versioned
    .get({
      path: '/',
      access: 'public',
      enableQueryVersion: true,
    })
    .addVersion(
      {
        validate: false,
        version: '2023-10-31',
        options: {
          deprecated: {
            documentationLink: 'https://www.elastic.co/guide/en/kibana/current/api.html',
            severity: 'warning',
            reason: {
              type: 'bump',
              newApiVersion: '2024-10-13',
            },
          },
        },
      },

See these instructions on adding a guide and this example PR, guides are required for each deprecation!
Check the PR notes or docs to learn more #196081

Saved objects APIs

/api/saved_objects/{type}/{id}
/api/saved_objects/resolve/{type}/{id}
/api/saved_objects/{type}/{id?}
/api/saved_objects/{type}/{id}
/api/saved_objects/_find
/api/saved_objects/{type}/{id}
/api/saved_objects/_bulk_get
/api/saved_objects/_bulk_create
/api/saved_objects/_bulk_resolve
/api/saved_objects/_bulk_update
/api/saved_objects/_bulk_delete

Actions APIs

/api/actions/action
/api/actions/action/{id}
/api/actions/action/{id}
/api/actions
/api/actions/action/{id}
/api/actions/list_action_types
/api/actions/action/{id}/_execute

Alerts APIs

/api/alerts/alert/{id?}
/api/alerts/alert/{id}
/api/alerts/_find
/api/alerts/alert/{id}
/api/alerts/alert/{id}/state
/api/alerts/alert/{id}/_instance_summary
/api/alerts/list_alert_types
/api/alerts/alert/{id}
/api/alerts/alert/{id}/_enable
/api/alerts/alert/{id}/_disable
/api/alerts/alert/{id}/_update_api_key
/api/alerts/alert/{id}/_mute_all
/api/alerts/alert/{id}/_unmute_all
/api/alerts/alert/{alert_id}/alert_instance/{alert_instance_id}/_mute
/api/alerts/alert/{alertId}/alert_instance/{alertInstanceId}/_unmute
/api/alerts/_health

Cases APIs

/api/cases/{case_id}/user_actions
/api/cases/status
/api/cases/{case_id}/comments

[jloleysens]

Saved objects APIs

While it's true these are deprecated, bc we decided to slow down removal we might need to hold off surfacing this in the UA until viable alternatives are ready for main use cases.

[TinaHeiligers]

Saved objects APIs

While it's true these are deprecated, bc we decided to slow down removal we might need to hold off surfacing this in the UA until viable alternatives are ready for main use cases.

I'd prefer to surface these now and continue to do so throughout v9 because they're widely used.

router[versioned?].get(
    {
      path: '/',
      options: {
        deprecated: {
           documentationUrl: 'https://www.elastic.co/guide/en/kibana/current/api.html',
           severity: 'warning',
           reason: {
              type: 'remove',
            },
        },
      },
    },
    async (context, req, res) => {

While it's true we don't have alternatives for all SO types (and probably never will), there are some and the docs point users to those: https://www.elastic.co/guide/en/kibana/current/api.html.

The other reason we should make a noise now is that we've been trying to get rid of the SO APIs for 4+ years and the deprecation of these specific APIs is generally ignored.

[elasticmachine]

Pinging @elastic/response-ops (Team:ResponseOps)

[elasticmachine]

Pinging @elastic/kibana-core (Team:Core)

[TinaHeiligers]

For the record, Core decided not to surface the deprecated global saved objects HTTP APIs in the upgrade assistant as critical warnings, since they are not being removed in 9.0.