[8.x] [Response Ops][Cases] Use deprecation object (#201004) (#201935)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[Response Ops][Cases] Use deprecation object
(#201004)](https://github.com/elastic/kibana/pull/201004)

<!--- Backport version: 9.4.3 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Julian
Gernun","email":"17549662+jcger@users.noreply.github.com"},"sourceCommit":{"committedDate":"2024-11-27T10:37:49Z","message":"[Response
Ops][Cases] Use deprecation object (#201004)\n\n## Summary\r\n\r\nAdds
deprecation object in deprecated cases routes\r\n\r\nCloses
[#196557](https://github.com/elastic/kibana/issues/196557)\r\n\r\n---------\r\n\r\nCo-authored-by:
Lisa Cawley
<lcawley@elastic.co>","sha":"0735ab8196e7d11fb099b564b2c9b03ce840aa36","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:ResponseOps","v9.0.0","Feature:Cases","backport:prev-minor","v8.18.0"],"title":"[Response
Ops][Cases] Use deprecation
object","number":201004,"url":"https://github.com/elastic/kibana/pull/201004","mergeCommit":{"message":"[Response
Ops][Cases] Use deprecation object (#201004)\n\n## Summary\r\n\r\nAdds
deprecation object in deprecated cases routes\r\n\r\nCloses
[#196557](https://github.com/elastic/kibana/issues/196557)\r\n\r\n---------\r\n\r\nCo-authored-by:
Lisa Cawley
<lcawley@elastic.co>","sha":"0735ab8196e7d11fb099b564b2c9b03ce840aa36"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/201004","number":201004,"mergeCommit":{"message":"[Response
Ops][Cases] Use deprecation object (#201004)\n\n## Summary\r\n\r\nAdds
deprecation object in deprecated cases routes\r\n\r\nCloses
[#196557](https://github.com/elastic/kibana/issues/196557)\r\n\r\n---------\r\n\r\nCo-authored-by:
Lisa Cawley
<lcawley@elastic.co>","sha":"0735ab8196e7d11fb099b564b2c9b03ce840aa36"}},{"branch":"8.x","label":"v8.18.0","branchLabelMappingKey":"^v8.18.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Co-authored-by: Julian Gernun <17549662+jcger@users.noreply.github.com>

docs/upgrade-notes.asciidoc

@@ -50,6 +50,27 @@ For Elastic Security release information, refer to {security-guide}/release-note
 ==== Kibana APIs
 
 [discrete]
+[[breaking-201004]]
+.[Cases] Legacy deprecations (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.
+====
+
 [[breaking-199656]]
 .Removed all security v1 endpoints (9.0.0)
 [%collapsible]
@@ -1832,4 +1853,3 @@ NOTE: For the complete Elastic Security solution release information, refer to {
 
 
 
-

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

@@ -1008,5 +1008,8 @@ export const getDocLinks = ({ kibanaBranch, buildFlavor }: GetDocLinkOptions): D
     inferenceManagement: {
       inferenceAPIDocumentation: `${ELASTIC_WEBSITE_URL}docs/api/doc/elasticsearch/operation/operation-inference-put`,
     },
+    cases: {
+      legacyApiDeprecations: `${KIBANA_DOCS}breaking-changes-summary.html#breaking-201004`,
+    },
   });
 };

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

@@ -682,6 +682,9 @@ export interface DocLinks {
   readonly inferenceManagement: {
     readonly inferenceAPIDocumentation: string;
   };
+  readonly cases: {
+    readonly legacyApiDeprecations: string;
+  };
 }
 
 export type BuildFlavor = 'serverless' | 'traditional';

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

@@ -131,7 +131,7 @@ export class CasePlugin
     registerRoutes({
       router,
       routes: [
-        ...getExternalRoutes({ isServerless }),
+        ...getExternalRoutes({ isServerless, docLinks: core.docLinks }),
         ...getInternalRoutes(this.userProfileService),
       ],
       logger: this.logger,

x-pack/plugins/cases/server/routes/api/comments/get_all_comment.test.ts

@@ -6,17 +6,40 @@
  */
 
 import { getAllCommentsRoute } from './get_all_comment';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 describe('getAllCommentsRoute', () => {
+  const docLinks = docLinksServiceMock.createSetupContract();
+
   it('marks the endpoint internal in serverless', async () => {
-    const router = getAllCommentsRoute({ isServerless: true });
+    const router = getAllCommentsRoute({ isServerless: true, docLinks });
 
     expect(router.routerOptions?.access).toBe('internal');
   });
 
   it('marks the endpoint public in non-serverless', async () => {
-    const router = getAllCommentsRoute({ isServerless: false });
+    const router = getAllCommentsRoute({ isServerless: false, docLinks });
 
     expect(router.routerOptions?.access).toBe('public');
   });
+
+  it('should be deprecated', () => {
+    const router = getAllCommentsRoute({ docLinks });
+    expect(router.routerOptions?.deprecated).toMatchInlineSnapshot(
+      {
+        documentationUrl: expect.stringMatching(/#breaking-201004$/),
+      },
+      `
+      Object {
+        "documentationUrl": StringMatching /#breaking-201004\\$/,
+        "reason": Object {
+          "newApiMethod": "GET",
+          "newApiPath": "/api/cases/{case_id}/comments/_find",
+          "type": "migrate",
+        },
+        "severity": "warning",
+      }
+    `
+    );
+  });
 });

x-pack/plugins/cases/server/routes/api/comments/get_all_comment.ts

@@ -7,6 +7,7 @@
 
 import { schema } from '@kbn/config-schema';
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import { CASE_COMMENTS_URL } from '../../../../common/constants';
 import { createCaseError } from '../../../common/error';
 import { createCasesRoute } from '../create_cases_route';
@@ -15,7 +16,13 @@ import type { attachmentDomainV1 } from '../../../../common/types/domain';
 /**
  * @deprecated since version 8.1.0
  */
-export const getAllCommentsRoute = ({ isServerless }: { isServerless?: boolean }) =>
+export const getAllCommentsRoute = ({
+  isServerless,
+  docLinks,
+}: {
+  isServerless?: boolean;
+  docLinks: DocLinksServiceSetup;
+}) =>
   createCasesRoute({
     method: 'get',
     path: CASE_COMMENTS_URL,
@@ -32,8 +39,15 @@ export const getAllCommentsRoute = ({ isServerless }: { isServerless?: boolean }
       summary: `Gets all case comments`,
       tags: ['oas-tag:cases'],
       // description: 'You must have `read` privileges for the **Cases** feature in the **Management**, **Observability**, or **Security** section of the Kibana feature privileges, depending on the owner of the cases with the comments you\'re seeking.',
-      // @ts-expect-error TODO(https://github.com/elastic/kibana/issues/196095): Replace {RouteDeprecationInfo}
-      deprecated: true,
+      deprecated: {
+        documentationUrl: docLinks.links.cases.legacyApiDeprecations,
+        severity: 'warning',
+        reason: {
+          type: 'migrate',
+          newApiMethod: 'GET',
+          newApiPath: '/api/cases/{case_id}/comments/_find',
+        },
+      },
     },
     handler: async ({ context, request, response }) => {
       try {

x-pack/plugins/cases/server/routes/api/get_external_routes.ts

@@ -5,6 +5,7 @@
  * 2.0.
  */
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import { getCasesByAlertIdRoute } from './cases/alerts/get_cases';
 import { deleteCaseRoute } from './cases/delete_cases';
 import { findCaseRoute } from './cases/find_cases';
@@ -32,7 +33,13 @@ import { getAllAlertsAttachedToCaseRoute } from './comments/get_alerts';
 import { findUserActionsRoute } from './user_actions/find_user_actions';
 import { postFileRoute } from './files/post_file';
 
-export const getExternalRoutes = ({ isServerless }: { isServerless?: boolean }) =>
+export const getExternalRoutes = ({
+  isServerless,
+  docLinks,
+}: {
+  isServerless?: boolean;
+  docLinks: DocLinksServiceSetup;
+}) =>
   [
     deleteCaseRoute,
     findCaseRoute,
@@ -42,8 +49,8 @@ export const getExternalRoutes = ({ isServerless }: { isServerless?: boolean })
     postCaseRoute,
     pushCaseRoute,
     findUserActionsRoute,
-    getUserActionsRoute({ isServerless }),
-    getStatusRoute({ isServerless }),
+    getUserActionsRoute({ isServerless, docLinks }),
+    getStatusRoute({ isServerless, docLinks }),
     getCasesByAlertIdRoute,
     getReportersRoute,
     getTagsRoute,
@@ -51,7 +58,7 @@ export const getExternalRoutes = ({ isServerless }: { isServerless?: boolean })
     deleteAllCommentsRoute,
     findCommentsRoute,
     getCommentRoute,
-    getAllCommentsRoute({ isServerless }),
+    getAllCommentsRoute({ isServerless, docLinks }),
     patchCommentRoute,
     postCommentRoute,
     getCaseConfigureRoute,

x-pack/plugins/cases/server/routes/api/stats/get_status.test.ts

@@ -6,16 +6,33 @@
  */
 
 import { getStatusRoute } from './get_status';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 describe('getStatusRoute', () => {
+  const docLinks = docLinksServiceMock.createSetupContract();
+
   it('marks the endpoint internal in serverless', async () => {
-    const router = getStatusRoute({ isServerless: true });
+    const router = getStatusRoute({ isServerless: true, docLinks });
 
     expect(router.routerOptions?.access).toBe('internal');
+    expect(router.routerOptions?.deprecated).toMatchInlineSnapshot(
+      {
+        documentationUrl: expect.stringMatching(/#breaking-201004$/),
+      },
+      `
+      Object {
+        "documentationUrl": StringMatching /#breaking-201004\\$/,
+        "reason": Object {
+          "type": "remove",
+        },
+        "severity": "warning",
+      }
+    `
+    );
   });
 
   it('marks the endpoint public in non-serverless', async () => {
-    const router = getStatusRoute({ isServerless: false });
+    const router = getStatusRoute({ isServerless: false, docLinks });
 
     expect(router.routerOptions?.access).toBe('public');
   });

x-pack/plugins/cases/server/routes/api/stats/get_status.ts

@@ -5,6 +5,7 @@
  * 2.0.
  */
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import type { CaseRoute } from '../types';
 
 import { CASE_STATUS_URL } from '../../../../common/constants';
@@ -15,7 +16,13 @@ import type { statsApiV1 } from '../../../../common/types/api';
 /**
  * @deprecated since version 8.1.0
  */
-export const getStatusRoute = ({ isServerless }: { isServerless?: boolean }): CaseRoute =>
+export const getStatusRoute = ({
+  isServerless,
+  docLinks,
+}: {
+  isServerless?: boolean;
+  docLinks: DocLinksServiceSetup;
+}): CaseRoute =>
   createCasesRoute({
     method: 'get',
     path: CASE_STATUS_URL,
@@ -27,8 +34,13 @@ export const getStatusRoute = ({ isServerless }: { isServerless?: boolean }): Ca
       description:
         'Returns the number of cases that are open, closed, and in progress in the default space.',
       // You must have `read` privileges for the **Cases** feature in the **Management**, **Observability**, or **Security** section of the Kibana feature privileges, depending on the owner of the cases you're seeking.
-      // @ts-expect-error TODO(https://github.com/elastic/kibana/issues/196095): Replace {RouteDeprecationInfo}
-      deprecated: true,
+      deprecated: {
+        documentationUrl: docLinks.links.cases.legacyApiDeprecations,
+        severity: 'warning',
+        reason: {
+          type: 'remove',
+        },
+      },
     },
     handler: async ({ context, request, response }) => {
       try {

x-pack/plugins/cases/server/routes/api/user_actions/get_all_user_actions.test.ts

@@ -6,16 +6,35 @@
  */
 
 import { getUserActionsRoute } from './get_all_user_actions';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 describe('getUserActionsRoute', () => {
+  const docLinks = docLinksServiceMock.createSetupContract();
+
   it('marks the endpoint internal in serverless', async () => {
-    const router = getUserActionsRoute({ isServerless: true });
+    const router = getUserActionsRoute({ isServerless: true, docLinks });
 
     expect(router.routerOptions?.access).toBe('internal');
+    expect(router.routerOptions?.deprecated).toMatchInlineSnapshot(
+      {
+        documentationUrl: expect.stringMatching(/#breaking-201004$/),
+      },
+      `
+      Object {
+        "documentationUrl": StringMatching /#breaking-201004\\$/,
+        "reason": Object {
+          "newApiMethod": "GET",
+          "newApiPath": "/api/cases/<case_id>/user_actions/_find",
+          "type": "migrate",
+        },
+        "severity": "warning",
+      }
+    `
+    );
   });
 
   it('marks the endpoint public in non-serverless', async () => {
-    const router = getUserActionsRoute({ isServerless: false });
+    const router = getUserActionsRoute({ isServerless: false, docLinks });
 
     expect(router.routerOptions?.access).toBe('public');
   });

x-pack/plugins/cases/server/routes/api/user_actions/get_all_user_actions.ts

@@ -7,6 +7,7 @@
 
 import { schema } from '@kbn/config-schema';
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import type { userActionApiV1 } from '../../../../common/types/api';
 import { CASE_USER_ACTIONS_URL } from '../../../../common/constants';
 import { createCaseError } from '../../../common/error';
@@ -15,7 +16,13 @@ import { createCasesRoute } from '../create_cases_route';
 /**
  * @deprecated since version 8.1.0
  */
-export const getUserActionsRoute = ({ isServerless }: { isServerless?: boolean }) =>
+export const getUserActionsRoute = ({
+  isServerless,
+  docLinks,
+}: {
+  isServerless?: boolean;
+  docLinks: DocLinksServiceSetup;
+}) =>
   createCasesRoute({
     method: 'get',
     path: CASE_USER_ACTIONS_URL,
@@ -31,8 +38,15 @@ export const getUserActionsRoute = ({ isServerless }: { isServerless?: boolean }
       description: `Returns all user activity for a case.`,
       // You must have `read` privileges for the **Cases** feature in the **Management**, **Observability**, or **Security** section of the Kibana feature privileges, depending on the owner of the case you're seeking.
       tags: ['oas-tag:cases'],
-      // @ts-expect-error TODO(https://github.com/elastic/kibana/issues/196095): Replace {RouteDeprecationInfo}
-      deprecated: true,
+      deprecated: {
+        documentationUrl: docLinks.links.cases.legacyApiDeprecations,
+        severity: 'warning',
+        reason: {
+          type: 'migrate',
+          newApiMethod: 'GET',
+          newApiPath: '/api/cases/<case_id>/user_actions/_find',
+        },
+      },
     },
     handler: async ({ context, request, response }) => {
       try {