[8.x] [UA][Core] Surface integrations with internal APIs in upgrade assistant (#199026)

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',
+  };
+};