integration tests

examples/routing_example/common/index.ts

@@ -20,7 +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/internal.ts

@@ -16,6 +16,7 @@ export const registerInternalDeprecatedRoute = (router: IRouter) => {
       path: DEPRECATED_ROUTES.INTERNAL_DEPRECATED_ROUTE,
       validate: false,
       options: {
+        // Explicitly set access is to internal
         access: 'internal',
         deprecated: {
           documentationUrl: 'https://elastic.co/',
@@ -39,9 +40,7 @@ export const registerInternalDeprecatedRoute = (router: IRouter) => {
     {
       path: DEPRECATED_ROUTES.INTERNAL_ONLY_ROUTE,
       validate: false,
-      options: {
-        access: 'internal',
-      },
+      // If no access is specified then it defaults to internal
     },
     async (ctx, req, res) => {
       return res.ok({

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

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

@@ -11,13 +11,21 @@ import type {
   ApiDeprecationDetails,
   DomainDeprecationDetails,
 } from '@kbn/core-deprecations-common';
+import { CoreKibanaRequest } from '@kbn/core-http-router-server-internal';
 import type { BuildApiDeprecationDetailsParams } from '../types';
 import {
   getApiDeprecationMessage,
   getApiDeprecationsManualSteps,
   getApiDeprecationTitle,
 } from './i18n_texts';
 
+export const getIsAccessApiDeprecation = (req: CoreKibanaRequest): boolean => {
+  const isNotPublicAccess = req.route.options.access !== 'public';
+  const isNotInternalRequest = !req.isInternalApiRequest;
+
+  return !!(isNotPublicAccess && isNotInternalRequest);
+};
+
 export const buildApiAccessDeprecationDetails = ({
   apiUsageStats,
   deprecatedApiDetails,

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

@@ -7,4 +7,4 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
-export { buildApiAccessDeprecationDetails } from './access_deprecations';
+export { buildApiAccessDeprecationDetails, getIsAccessApiDeprecation } from './access_deprecations';

packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/index.ts

@@ -8,4 +8,6 @@
  */
 
 export { registerApiDeprecationsInfo } from './register_api_depercation_info';
+export { getIsAccessApiDeprecation } from './access';
+export { getIsRouteApiDeprecation } from './route';
 export { buildApiDeprecationId } from './api_deprecation_id';

packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/register_api_depercation_info.ts

@@ -38,17 +38,17 @@ export const createGetApiDeprecations =
         }
 
         const { routeAccess } = deprecatedApiDetails;
-
         switch (routeAccess) {
-          case 'internal': {
-            return buildApiAccessDeprecationDetails({
+          case 'public': {
+            return buildApiRouteDeprecationDetails({
               apiUsageStats,
               deprecatedApiDetails,
             });
           }
-          case 'public':
+          // if no access is specified then internal is the default
+          case 'internal':
           default: {
-            return buildApiRouteDeprecationDetails({
+            return buildApiAccessDeprecationDetails({
               apiUsageStats,
               deprecatedApiDetails,
             });

packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/index.ts

@@ -7,4 +7,4 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
-export { buildApiRouteDeprecationDetails } from './route_deprecations';
+export { buildApiRouteDeprecationDetails, getIsRouteApiDeprecation } from './route_deprecations';

packages/core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations/route/route_deprecations.ts

@@ -11,12 +11,26 @@ import type {
   ApiDeprecationDetails,
   DomainDeprecationDetails,
 } from '@kbn/core-deprecations-common';
-import type { BuildApiDeprecationDetailsParams } from '../types';
+
+import { CoreKibanaRequest } from '@kbn/core-http-router-server-internal';
+import _ from 'lodash';
+import { RouteDeprecationInfo } from '@kbn/core-http-server';
 import {
   getApiDeprecationMessage,
   getApiDeprecationsManualSteps,
   getApiDeprecationTitle,
 } from './i18n_texts';
+import type { BuildApiDeprecationDetailsParams } from '../types';
+
+export const getIsRouteApiDeprecation = (
+  req: CoreKibanaRequest,
+  deprecated?: RouteDeprecationInfo
+): boolean => {
+  const hasDeprecatedObject = deprecated && _.isObject(deprecated);
+  const isNotInternalRequest = !req.isInternalApiRequest;
+
+  return !!(hasDeprecatedObject && isNotInternalRequest);
+};
 
 export const buildApiRouteDeprecationDetails = ({
   apiUsageStats,

packages/core/deprecations/core-deprecations-server-internal/src/deprecations/index.ts

@@ -7,5 +7,10 @@
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
 
-export { buildApiDeprecationId, registerApiDeprecationsInfo } from './api_deprecations';
+export {
+  buildApiDeprecationId,
+  registerApiDeprecationsInfo,
+  getIsAccessApiDeprecation,
+  getIsRouteApiDeprecation,
+} from './api_deprecations';
 export { registerConfigDeprecationsInfo } from './config_deprecations';

packages/core/deprecations/core-deprecations-server-internal/src/routes/get.ts

@@ -14,6 +14,9 @@ export const registerGetRoute = (router: InternalDeprecationRouter) => {
   router.get(
     {
       path: '/',
+      options: {
+        access: 'public',
+      },
       validate: false,
     },
     async (context, req, res) => {

packages/core/deprecations/core-deprecations-server-internal/src/routes/post_validation_handler.ts

@@ -10,9 +10,9 @@
 import type { InternalCoreUsageDataSetup } from '@kbn/core-usage-data-server-internal';
 import type { CoreKibanaRequest } from '@kbn/core-http-router-server-internal';
 import type { InternalHttpServiceSetup } from '@kbn/core-http-server-internal';
-import { isObject } from 'lodash';
-import { RouteDeprecationInfo } from '@kbn/core-http-server/src/router/route'; // shouldn't use deep imports
+import { RouteDeprecationInfo } from '@kbn/core-http-server';
 import { buildApiDeprecationId } from '../deprecations';
+import { getIsRouteApiDeprecation, getIsAccessApiDeprecation } from '../deprecations';
 
 interface Dependencies {
   coreUsageData: InternalCoreUsageDataSetup;
@@ -36,8 +36,9 @@ export function createRouteDeprecationsHandler({
   coreUsageData: InternalCoreUsageDataSetup;
 }) {
   return (req: CoreKibanaRequest, { deprecated }: { deprecated?: RouteDeprecationInfo }) => {
-    const hasRouteDeprecation = deprecated && isObject(deprecated);
-    const hasAccessDeprecation = req.route.options.access === 'internal';
+    const hasRouteDeprecation = getIsRouteApiDeprecation(req, deprecated);
+    const hasAccessDeprecation = getIsAccessApiDeprecation(req);
+
     const isApiDeprecation = hasAccessDeprecation || hasRouteDeprecation;
     if (isApiDeprecation && req.route.routePath) {
       const counterName = buildApiDeprecationId({

packages/core/deprecations/core-deprecations-server-internal/src/routes/resolve_deprecated_api.ts

@@ -19,6 +19,9 @@ export const registerMarkAsResolvedRoute = (
   router.post(
     {
       path: '/mark_as_resolved',
+      options: {
+        access: 'internal',
+      },
       validate: {
         body: schema.object({
           domainId: schema.string(),

src/plugins/telemetry/schema/oss_plugins.json

@@ -9290,6 +9290,18 @@
           "_meta": {
             "description": "How many times a saved object has resolved with any of the four possible outcomes."
           }
+        },
+        "deprecated_api_calls_resolved.total": {
+          "type": "integer",
+          "_meta": {
+            "description": "How many times deprecated APIs has been marked as resolved"
+          }
+        },
+        "deprecated_api_calls.total": {
+          "type": "integer",
+          "_meta": {
+            "description": "How many times deprecated APIs has been called."
+          }
         }
       }
     },

x-pack/plugins/upgrade_assistant/README.md

@@ -287,8 +287,7 @@ Run them in the console to trigger the deprecation condition so they show up in
 
 ```
 # Route deprecations for Versioned routes: Version 1 is deprecated
-GET kbn:/api/routing_example/d/versioned?apiVersion=1
-GET kbn:/api/routing_example/d/versioned?apiVersion=2
+GET kbn:/api/routing_example/d/versioned_route?apiVersion=2023-10-31
 
 # Route deprecations for Non-versioned routes
 GET kbn:/api/routing_example/d/removed_route
@@ -299,12 +298,12 @@ POST kbn:/api/routing_example/d/migrated_route
 # Access deprecations
 GET kbn:/api/routing_example/d/internal_deprecated_route
 GET kbn:/internal/routing_example/d/internal_only_route
+GET kbn:/internal/routing_example/d/internal_versioned_route?apiVersion=1
 ```
 
 1. You can also mark as deprecated in the UA to remove the deprecation from the list.
 2. Check the telemetry response to see the reported data about the deprecated route.
-3. Calling version 2 of the API  does not do anything since it is not deprecated unlike version `1` (`GET kbn:/api/routing_example/d/versioned?apiVersion=2`)
-4. Internally you can see the deprecations counters from the dev console by running the following:
+3. Internally you can see the deprecations counters from the dev console by running the following:
 ```
 GET .kibana_usage_counters/_search
 {