[ResponseOps][Alerting] Add deprecation object to legacy rule endpoin…

…ts (elastic#201550)

## Summary

Adds deprecation object in deprecated alerting routes

Closes elastic#196556

---------

Co-authored-by: lcawl <[email protected]>

docs/CHANGELOG.asciidoc

@@ -27,6 +27,59 @@ For information about the {kib} 9.0.0 release, review the following information.
 [[breaking-changes-9.0.0]]
 === Breaking changes
 
+[discrete]
+.Removed legacy alerting endpoints (9.0.0)
+[%collapsible]
+====
+*Details* +
+--
+* `POST /api/alerts/alert/{id?}` has been replaced by `POST /api/alerting/rule/{id?}`
+* `GET /api/alerts/alert/{id}` has been replaced by `GET /api/alerting/rule/{id}`
+* `PUT /api/alerts/alert/{id}` has been replaced by `PUT /api/alerting/rule/rule/{id}`
+* `DELETE: /api/alerts/alert/{id}` has been replaced by `DELETE /api/alerting/rule/{id}`
+* `POST /api/alerts/alert/{id}/_disable` has been replaced by `POST /api/alerting/rule/{id}/_disable`
+* `POST /api/alerts/alert/{id}/_enable` has been replaced by `POST /api/alerting/rule/{id}/_enable`
+* `GET /api/alerts/_find` has been replaced by `GET /api/alerting/rules/_find`
+* `GET /api/alerts/_health` has been replaced by `GET /api/alerting/rule/_health`
+* `GET /api/alerts/list_alert_types` has been replaced by `GET /api/alerting/rule_types`
+* `POST /api/alerts/alert/{alert_id}/alert_instance/{alert_instance_id}/_mute` has been replaced by `POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute`
+* `POST /api/alerts/alert/{alert_id}/alert_instance/{alert_instance_id}/_unmute` has been replaced by `POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute`
+* `POST /api/alerts/alert/{id}/_mute_all` has been replaced by `POST /api/alerting/rule/{id}/_mute_all`
+* `POST /api/alerts/alert/{id}/_unmute_all` has been replaced by `POST /api/alerting/rule/{id}/_unmute_all`
+* `POST /api/alerts/alert/{id}/_update_api_key` has been replaced by `POST /api/alerting/rule/{id}/_update_api_key`
+* `GET /api/alerts/{id}/_instance_summary` has been deprecated without replacement. Will be removed in v9.0.0
+* `GET /api/alerts/{id}/state` has been deprecated without replacement. Will be removed in v9.0.0
+--
+
+*Impact* +
+Deprecated endpoints will fail with a 404 status code starting from version 9.0.0
+
+*Action* +
+Remove references to `GET /api/alerts/{id}/_instance_summary` endpoint.
+Remove references to `GET /api/alerts/{id}/state` endpoint.
+Replace references to endpoints listed as deprecated by it's replacement. See `Details` section.
+The updated APIs can be found in {api-kibana}/group/endpoint-alerting
+====
+
+.Removed legacy cases endpoints (9.0.0)
+[%collapsible]
+====
+*Details* +
+--
+* `GET /api/cases/status` has been deprecated with no replacement. Deleted in v9.0.0
+* `GET /api/cases/{case_id}/comments` has been replaced by `GET /api/cases/{case_id}/comments/_find` released in v7.13
+* `GET /api/cases/<case_id>/user_actions` has been replaced by `GET /api/cases/<case_id>/user_actions/_find` released in v8.7
+* `includeComments` parameter in `GET /api/cases/{case_id}` has been deprecated. Use `GET /api/cases/{case_id}/comments/_find` instead, released in v7.13
+--
+
+*Impact* +
+Deprecated endpoints will fail with a 404 status code starting from version 9.0.0
+
+*Action* +
+Remove references to `GET /api/cases/status` endpoint.
+Replace references to deprecated endpoints with the replacements listed in the breaking change details.
+====
+
 [discrete]
 .Removed all security v1 endpoints (9.0.0)
 [%collapsible]

docs/upgrade-notes.asciidoc

@@ -50,18 +50,51 @@ For Elastic Security solution release information, refer to {security-guide}/rel
 
 
 [discrete]
-[[breaking-201004]]
-.[Cases] Legacy deprecations (9.0.0)
+[[breaking-201550]]
+.Removed legacy alerting endpoints (9.0.0)
 [%collapsible]
 ====
 *Details* +
-`GET /api/cases/status` has been deprecated with no replacement. Deleted in v9.0.0
+--
+* `POST /api/alerts/alert/{id?}` has been replaced by `POST /api/alerting/rule/{id?}`
+* `GET /api/alerts/alert/{id}` has been replaced by `GET /api/alerting/rule/{id}`
+* `PUT /api/alerts/alert/{id}` has been replaced by `PUT /api/alerting/rule/rule/{id}`
+* `DELETE: /api/alerts/alert/{id}` has been replaced by `DELETE /api/alerting/rule/{id}`
+* `POST /api/alerts/alert/{id}/_disable` has been replaced by `POST /api/alerting/rule/{id}/_disable`
+* `POST /api/alerts/alert/{id}/_enable` has been replaced by `POST /api/alerting/rule/{id}/_enable`
+* `GET /api/alerts/_find` has been replaced by `GET /api/alerting/rules/_find`
+* `GET /api/alerts/_health` has been replaced by `GET /api/alerting/rule/_health`
+* `GET /api/alerts/list_alert_types` has been replaced by `GET /api/alerting/rule_types`
+* `POST /api/alerts/alert/{alert_id}/alert_instance/{alert_instance_id}/_mute` has been replaced by `POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute`
+* `POST /api/alerts/alert/{alert_id}/alert_instance/{alert_instance_id}/_unmute` has been replaced by `POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute`
+* `POST /api/alerts/alert/{id}/_mute_all` has been replaced by `POST /api/alerting/rule/{id}/_mute_all`
+* `POST /api/alerts/alert/{id}/_unmute_all` has been replaced by `POST /api/alerting/rule/{id}/_unmute_all`
+* `POST /api/alerts/alert/{id}/_update_api_key` has been replaced by `POST /api/alerting/rule/{id}/_update_api_key`
+* `GET /api/alerts/{id}/_instance_summary` has been deprecated without replacement. Will be removed in v9.0.0
+* `GET /api/alerts/{id}/state` has been deprecated without replacement. Will be removed in v9.0.0
+--
 
-`GET /api/cases/{case_id}/comments` has been replaced by `GET /api/cases/{case_id}/comments/_find` released in v7.13
+*Impact* +
+Deprecated endpoints will fail with a 404 status code starting from version 9.0.0
 
-`GET /api/cases/<case_id>/user_actions` has been replaced by `GET /api/cases/<case_id>/user_actions/_find` released in v8.7
+*Action* +
+Remove references to `GET /api/alerts/{id}/_instance_summary` endpoint.
+Remove references to `GET /api/alerts/{id}/state` endpoint.
+Replace references to endpoints listed as deprecated by it's replacement. See `Details` section.
+The updated APIs can be found here https://www.elastic.co/docs/api/doc/kibana/v8/group/endpoint-alerting
+====
 
-`includeComments` parameter in `GET /api/cases/{case_id}` has been deprecated. Use `GET /api/cases/{case_id}/comments/_find` instead, released in v7.13
+[[breaking-201004]]
+.Removed legacy cases endpoints (9.0.0)
+[%collapsible]
+====
+*Details* +
+--
+* `GET /api/cases/status` has been deprecated with no replacement. Deleted in v9.0.0
+* `GET /api/cases/{case_id}/comments` has been replaced by `GET /api/cases/{case_id}/comments/_find` released in v7.13
+* `GET /api/cases/<case_id>/user_actions` has been replaced by `GET /api/cases/<case_id>/user_actions/_find` released in v8.7
+* `includeComments` parameter in `GET /api/cases/{case_id}` has been deprecated. Use `GET /api/cases/{case_id}/comments/_find` instead, released in v7.13
+--
 
 *Impact* +
 Deprecated endpoints will fail with a 404 status code starting from version 9.0.0

packages/kbn-doc-links/src/get_doc_links.ts

@@ -672,6 +672,7 @@ export const getDocLinks = ({ kibanaBranch, buildFlavor }: GetDocLinkOptions): D
       slackApiAction: `${KIBANA_DOCS}slack-action-type.html#configuring-slack-web-api`,
       teamsAction: `${KIBANA_DOCS}teams-action-type.html#configuring-teams`,
       connectors: `${KIBANA_DOCS}action-types.html`,
+      legacyRuleApiDeprecations: `${KIBANA_DOCS}breaking-changes-summary.html#breaking-201550`,
     },
     taskManager: {
       healthMonitoring: `${KIBANA_DOCS}task-manager-health-monitoring.html`,

packages/kbn-doc-links/src/types.ts

@@ -474,6 +474,7 @@ export interface DocLinks {
     slackApiAction: string;
     teamsAction: string;
     connectors: string;
+    legacyRuleApiDeprecations: string;
   }>;
   readonly taskManager: Readonly<{
     healthMonitoring: string;

x-pack/plugins/alerting/server/plugin.ts

@@ -411,6 +411,7 @@ export class AlertingPlugin {
       encryptedSavedObjects: plugins.encryptedSavedObjects,
       config$: plugins.unifiedSearch.autocomplete.getInitializerContextConfig().create(),
       isServerless: !!plugins.serverless,
+      docLinks: core.docLinks,
     });
 
     return {

x-pack/plugins/alerting/server/routes/index.ts

@@ -5,7 +5,7 @@
  * 2.0.
  */
 
-import { IRouter } from '@kbn/core/server';
+import { DocLinksServiceSetup, IRouter } from '@kbn/core/server';
 import { UsageCounter } from '@kbn/usage-collection-plugin/server';
 import { EncryptedSavedObjectsPluginSetup } from '@kbn/encrypted-saved-objects-plugin/server';
 import type { ConfigSchema } from '@kbn/unified-search-plugin/server/config';
@@ -81,6 +81,7 @@ export interface RouteOptions {
   usageCounter?: UsageCounter;
   config$?: Observable<ConfigSchema>;
   isServerless?: boolean;
+  docLinks: DocLinksServiceSetup;
 }
 
 export function defineRoutes(opts: RouteOptions) {

x-pack/plugins/alerting/server/routes/legacy/create.test.ts

@@ -16,6 +16,7 @@ import { Rule, RuleSystemAction } from '../../../common/rule';
 import { RuleTypeDisabledError } from '../../lib/errors/rule_type_disabled';
 import { encryptedSavedObjectsMock } from '@kbn/encrypted-saved-objects-plugin/server/mocks';
 import { trackLegacyRouteUsage } from '../../lib/track_legacy_route_usage';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 const rulesClient = rulesClientMock.create();
 
@@ -32,6 +33,7 @@ beforeEach(() => {
 });
 
 describe('createAlertRoute', () => {
+  const docLinks = docLinksServiceMock.createSetupContract();
   const createdAt = new Date();
   const updatedAt = new Date();
 
@@ -104,6 +106,7 @@ describe('createAlertRoute', () => {
       licenseState,
       encryptedSavedObjects,
       usageCounter: mockUsageCounter,
+      docLinks,
     });
 
     const [config, handler] = router.post.mock.calls[0];
@@ -179,6 +182,7 @@ describe('createAlertRoute', () => {
       encryptedSavedObjects,
       usageCounter: mockUsageCounter,
       isServerless: true,
+      docLinks,
     });
 
     const [config] = router.post.mock.calls[0];
@@ -204,6 +208,7 @@ describe('createAlertRoute', () => {
       licenseState,
       encryptedSavedObjects,
       usageCounter: mockUsageCounter,
+      docLinks,
     });
 
     const [config, handler] = router.post.mock.calls[0];
@@ -281,6 +286,7 @@ describe('createAlertRoute', () => {
       licenseState,
       encryptedSavedObjects,
       usageCounter: mockUsageCounter,
+      docLinks,
     });
 
     const [config, handler] = router.post.mock.calls[0];
@@ -359,6 +365,7 @@ describe('createAlertRoute', () => {
       licenseState,
       encryptedSavedObjects,
       usageCounter: mockUsageCounter,
+      docLinks,
     });
 
     const [config, handler] = router.post.mock.calls[0];
@@ -426,7 +433,7 @@ describe('createAlertRoute', () => {
     const router = httpServiceMock.createRouter();
     const encryptedSavedObjects = encryptedSavedObjectsMock.createSetup({ canEncrypt: true });
 
-    createAlertRoute({ router, licenseState, encryptedSavedObjects });
+    createAlertRoute({ router, licenseState, encryptedSavedObjects, docLinks });
 
     const [, handler] = router.post.mock.calls[0];
 
@@ -448,7 +455,7 @@ describe('createAlertRoute', () => {
       throw new Error('OMG');
     });
 
-    createAlertRoute({ router, licenseState, encryptedSavedObjects });
+    createAlertRoute({ router, licenseState, encryptedSavedObjects, docLinks });
 
     const [, handler] = router.post.mock.calls[0];
 
@@ -466,7 +473,7 @@ describe('createAlertRoute', () => {
     const router = httpServiceMock.createRouter();
     const encryptedSavedObjects = encryptedSavedObjectsMock.createSetup({ canEncrypt: true });
 
-    createAlertRoute({ router, licenseState, encryptedSavedObjects });
+    createAlertRoute({ router, licenseState, encryptedSavedObjects, docLinks });
 
     const [, handler] = router.post.mock.calls[0];
 
@@ -491,6 +498,7 @@ describe('createAlertRoute', () => {
       licenseState,
       encryptedSavedObjects,
       usageCounter: mockUsageCounter,
+      docLinks,
     });
     const [, handler] = router.post.mock.calls[0];
     rulesClient.create.mockResolvedValueOnce(createResult);
@@ -511,6 +519,7 @@ describe('createAlertRoute', () => {
       licenseState,
       encryptedSavedObjects,
       usageCounter: mockUsageCounter,
+      docLinks,
     });
 
     const [config, handler] = router.post.mock.calls[0];
@@ -570,4 +579,39 @@ describe('createAlertRoute', () => {
       body: createResult,
     });
   });
+
+  it('should be deprecated', () => {
+    const licenseState = licenseStateMock.create();
+    const router = httpServiceMock.createRouter();
+    const encryptedSavedObjects = encryptedSavedObjectsMock.createSetup({ canEncrypt: true });
+    const mockUsageCountersSetup = usageCountersServiceMock.createSetupContract();
+    const mockUsageCounter = mockUsageCountersSetup.createUsageCounter('test');
+
+    createAlertRoute({
+      router,
+      licenseState,
+      encryptedSavedObjects,
+      usageCounter: mockUsageCounter,
+      docLinks,
+    });
+
+    const [config] = router.post.mock.calls[0];
+
+    expect(config.options?.deprecated).toMatchInlineSnapshot(
+      {
+        documentationUrl: expect.stringMatching(/#breaking-201550$/),
+      },
+      `
+      Object {
+        "documentationUrl": StringMatching /#breaking-201550\\$/,
+        "reason": Object {
+          "newApiMethod": "POST",
+          "newApiPath": "/api/alerting/rule/{id?}",
+          "type": "migrate",
+        },
+        "severity": "warning",
+      }
+    `
+    );
+  });
 });

x-pack/plugins/alerting/server/routes/legacy/create.ts

@@ -49,6 +49,7 @@ export const createAlertRoute = ({
   licenseState,
   usageCounter,
   isServerless,
+  docLinks,
 }: RouteOptions) => {
   router.post(
     {
@@ -65,8 +66,15 @@ export const createAlertRoute = ({
         access: isServerless ? 'internal' : 'public',
         summary: 'Create an alert',
         tags: ['oas-tag:alerting'],
-        // @ts-expect-error TODO(https://github.com/elastic/kibana/issues/196095): Replace {RouteDeprecationInfo}
-        deprecated: true,
+        deprecated: {
+          documentationUrl: docLinks.links.alerting.legacyRuleApiDeprecations,
+          severity: 'warning',
+          reason: {
+            type: 'migrate',
+            newApiMethod: 'POST',
+            newApiPath: '/api/alerting/rule/{id?}',
+          },
+        },
       },
     },
     handleDisabledApiKeysError(