[UA][Core] Surface integrations with internal APIs in upgrade assista…

…nt (elastic#199026)

## Summary

> In elastic#117241 we're surfacing
usage of APIs marked as `deprecated: true` in the Upgrade Assistant to
help users prepare for a major upgrade. While internal APIs aren't
really deprecated in the same sense we are making a breaking change by
blocking external integrations with these APIs. Since this could be
equally disruptive to users depending on these APIs it would help our
users to surface such usage in the UA too.

The `api` deprecations now have two sub types:
1. routes deprecations `options.deprecated: { … }`
2. access deprecations `options.access: 'internal'`

This PR adds the second `api` deprecation subtype. The reason i kept one
`api` deprecation type and i didnt create a new type is that they have
exactly the same registration process but are triggered by different
attributes. The `api` deprecation is fully managed by the core team
internal services and are configured by the user through the route
interface so it makes sense to keep them as one type. I also can see us
adding more subtypes to this and just piggybacking on the current flow
instead of duplicating it everytime.


**Checklist**
- [x] Create deprecation subtype
- [x] Example plugin
- [x] Surface the deprecation in UA
- [x] Api access deprecation copy (@florent-leborgne )
- [x] Update README and code annotations
- [x] Unit tests
- [x] Integration tests


Closes elastic#194675

### Design decisions:
If the API has both route deprecation (`options.deprecated: { … }` ) AND
is an internal api `options.access: 'internal'`

The current behavior i went for in my PR:
I show this API once in the UA under the internal access deprecation.
While showing the route deprecation details if defined. This seems to
make the most sense since users should stop using this API altogether.

### Copy decisions:
@florent-leborgne wrote the copy for this deprecation subtype.
<img width="1319" alt="image"
src="https://github.com/user-attachments/assets/9a32f6d1-686a-4405-aec6-786ac5e10130">

<img width="713" alt="image"
src="https://github.com/user-attachments/assets/1304c98d-4c64-468e-a7d6-19c1193bf678">


## Testing

Run kibana locally with the test example plugin that has deprecated
routes
```
yarn start --plugin-path=examples/routing_example --plugin-path=examples/developer_examples
```

The following comprehensive deprecated routes examples are registered
inside the folder:
`examples/routing_example/server/routes/deprecated_routes`

Run them in the dev console to trigger the deprecation condition so they
show up in the UA:

```
GET kbn:/api/routing_example/d/internal_deprecated_route?elasticInternalOrigin=false
GET kbn:/internal/routing_example/d/internal_only_route?elasticInternalOrigin=false
GET kbn:/internal/routing_example/d/internal_versioned_route?apiVersion=1&elasticInternalOrigin=false
```

---------

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

examples/routing_example/common/index.ts

@@ -20,5 +20,8 @@ export const DEPRECATED_ROUTES = {
   DEPRECATED_ROUTE: '/api/routing_example/d/deprecated_route',
   REMOVED_ROUTE: '/api/routing_example/d/removed_route',
   MIGRATED_ROUTE: '/api/routing_example/d/migrated_route',
-  VERSIONED_ROUTE: '/api/routing_example/d/versioned',
+  VERSIONED_ROUTE: '/api/routing_example/d/versioned_route',
+  INTERNAL_DEPRECATED_ROUTE: '/api/routing_example/d/internal_deprecated_route',
+  INTERNAL_ONLY_ROUTE: '/internal/routing_example/d/internal_only_route',
+  VERSIONED_INTERNAL_ROUTE: '/internal/routing_example/d/internal_versioned_route',
 };

examples/routing_example/server/routes/deprecated_routes/index.ts

@@ -10,8 +10,10 @@
 import { IRouter } from '@kbn/core/server';
 import { registerDeprecatedRoute } from './unversioned';
 import { registerVersionedDeprecatedRoute } from './versioned';
+import { registerInternalDeprecatedRoute } from './internal';
 
 export function registerDeprecatedRoutes(router: IRouter) {
   registerDeprecatedRoute(router);
   registerVersionedDeprecatedRoute(router);
+  registerInternalDeprecatedRoute(router);
 }

examples/routing_example/server/routes/deprecated_routes/internal.ts

@@ -0,0 +1,54 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import type { IRouter } from '@kbn/core/server';
+import { DEPRECATED_ROUTES } from '../../../common';
+
+export const registerInternalDeprecatedRoute = (router: IRouter) => {
+  router.get(
+    {
+      path: DEPRECATED_ROUTES.INTERNAL_DEPRECATED_ROUTE,
+      validate: false,
+      options: {
+        // Explicitly set access is to internal
+        access: 'internal',
+        deprecated: {
+          documentationUrl: 'https://elastic.co/',
+          severity: 'critical',
+          message: 'Additonal message for internal deprecated api',
+          reason: { type: 'deprecate' },
+        },
+      },
+    },
+    async (ctx, req, res) => {
+      return res.ok({
+        body: {
+          result:
+            'Called deprecated route with `access: internal`. Check UA to see the deprecation.',
+        },
+      });
+    }
+  );
+
+  router.get(
+    {
+      path: DEPRECATED_ROUTES.INTERNAL_ONLY_ROUTE,
+      validate: false,
+      // If no access is specified then it defaults to internal
+    },
+    async (ctx, req, res) => {
+      return res.ok({
+        body: {
+          result:
+            'Called route with `access: internal` Although this API is not marked as deprecated it will show in UA. Check UA to see the deprecation.',
+        },
+      });
+    }
+  );
+};

examples/routing_example/server/routes/deprecated_routes/versioned.ts

@@ -11,42 +11,72 @@ import type { IRouter } from '@kbn/core/server';
 import { DEPRECATED_ROUTES } from '../../../common';
 
 export const registerVersionedDeprecatedRoute = (router: IRouter) => {
-  const versionedRoute = router.versioned.get({
-    path: DEPRECATED_ROUTES.VERSIONED_ROUTE,
-    description: 'Routing example plugin deprecated versioned route.',
-    access: 'internal',
-    options: {
-      excludeFromOAS: true,
-    },
-    enableQueryVersion: true,
-  });
-
-  versionedRoute.addVersion(
-    {
+  router.versioned
+    .get({
+      path: DEPRECATED_ROUTES.VERSIONED_ROUTE,
+      description: 'Routing example plugin deprecated versioned route.',
+      access: 'public',
       options: {
-        deprecated: {
-          documentationUrl: 'https://elastic.co/',
-          severity: 'warning',
-          reason: { type: 'bump', newApiVersion: '2' },
+        excludeFromOAS: true,
+      },
+      enableQueryVersion: true,
+    })
+    .addVersion(
+      {
+        options: {
+          deprecated: {
+            documentationUrl: 'https://elastic.co/',
+            severity: 'warning',
+            reason: { type: 'deprecate' },
+          },
         },
+        validate: false,
+        version: '2023-10-31',
       },
-      validate: false,
-      version: '1',
-    },
-    (ctx, req, res) => {
-      return res.ok({
-        body: { result: 'Called deprecated version of the API. API version 1 -> 2' },
-      });
-    }
-  );
+      (ctx, req, res) => {
+        return res.ok({
+          body: { result: 'Called deprecated version of the API "2023-10-31"' },
+        });
+      }
+    );
 
-  versionedRoute.addVersion(
-    {
-      version: '2',
-      validate: false,
-    },
-    (ctx, req, res) => {
-      return res.ok({ body: { result: 'Called API version 2' } });
-    }
-  );
+  router.versioned
+    .get({
+      path: DEPRECATED_ROUTES.VERSIONED_INTERNAL_ROUTE,
+      description: 'Routing example plugin deprecated versioned route.',
+      access: 'internal',
+      options: {
+        excludeFromOAS: true,
+      },
+      enableQueryVersion: true,
+    })
+    .addVersion(
+      {
+        options: {
+          deprecated: {
+            documentationUrl: 'https://elastic.co/',
+            severity: 'warning',
+            reason: { type: 'bump', newApiVersion: '2' },
+          },
+        },
+        validate: false,
+        version: '1',
+      },
+      (ctx, req, res) => {
+        return res.ok({
+          body: { result: 'Called internal deprecated version of the API 1.' },
+        });
+      }
+    )
+    .addVersion(
+      {
+        validate: false,
+        version: '2',
+      },
+      (ctx, req, res) => {
+        return res.ok({
+          body: { result: 'Called non-deprecated version of the API.' },
+        });
+      }
+    );
 };

examples/routing_example/server/routes/message_routes.ts

@@ -63,6 +63,9 @@ export function registerGetMessageByIdRoute(router: IRouter) {
   router.get(
     {
       path: `${INTERNAL_GET_MESSAGE_BY_ID_ROUTE}/{id}`,
+      options: {
+        access: 'internal',
+      },
       validate: {
         params: schema.object({
           id: schema.string(),

packages/core/deprecations/core-deprecations-common/index.ts

@@ -11,6 +11,7 @@ export type {
   BaseDeprecationDetails,
   ConfigDeprecationDetails,
   FeatureDeprecationDetails,
+  ApiDeprecationDetails,
   DeprecationsDetails,
   DomainDeprecationDetails,
   DeprecationsGetResponse,

packages/core/deprecations/core-deprecations-common/src/types.ts

@@ -121,7 +121,7 @@ export type DeprecationsDetails =
 /**
  * @public
  */
-export type DomainDeprecationDetails = DeprecationsDetails & {
+export type DomainDeprecationDetails<ExtendedDetails = DeprecationsDetails> = ExtendedDetails & {
   domainId: string;
 };
 

packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/access/access_deprecations.ts

@@ -0,0 +1,62 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import type {
+  ApiDeprecationDetails,
+  DomainDeprecationDetails,
+} from '@kbn/core-deprecations-common';
+
+import type { PostValidationMetadata } from '@kbn/core-http-server';
+import type { BuildApiDeprecationDetailsParams } from '../types';
+import {
+  getApiDeprecationMessage,
+  getApiDeprecationsManualSteps,
+  getApiDeprecationTitle,
+} from './i18n_texts';
+
+export const getIsAccessApiDeprecation = ({
+  isInternalApiRequest,
+  isPublicAccess,
+}: PostValidationMetadata): boolean => {
+  const isNotPublicAccess = !isPublicAccess;
+  const isNotInternalRequest = !isInternalApiRequest;
+
+  return !!(isNotPublicAccess && isNotInternalRequest);
+};
+
+export const buildApiAccessDeprecationDetails = ({
+  apiUsageStats,
+  deprecatedApiDetails,
+}: BuildApiDeprecationDetailsParams): DomainDeprecationDetails<ApiDeprecationDetails> => {
+  const { apiId, apiTotalCalls, totalMarkedAsResolved } = apiUsageStats;
+  const { routeVersion, routePath, routeDeprecationOptions, routeMethod } = deprecatedApiDetails;
+
+  const deprecationLevel = routeDeprecationOptions?.severity || 'warning';
+
+  return {
+    apiId,
+    title: getApiDeprecationTitle(deprecatedApiDetails),
+    level: deprecationLevel,
+    message: getApiDeprecationMessage(deprecatedApiDetails, apiUsageStats),
+    documentationUrl: routeDeprecationOptions?.documentationUrl,
+    correctiveActions: {
+      manualSteps: getApiDeprecationsManualSteps(),
+      mark_as_resolved_api: {
+        routePath,
+        routeMethod,
+        routeVersion,
+        apiTotalCalls,
+        totalMarkedAsResolved,
+        timestamp: new Date(),
+      },
+    },
+    deprecationType: 'api',
+    domainId: 'core.http.access-deprecations',
+  };
+};