[8.x] 🌊 Streams: Prepare API for publishing (#213127)

oas_docs/overlays/kibana.overlays.serverless.yaml

@@ -0,0 +1,85 @@
+# overlays.yaml
+overlay: 1.0.0
+info:
+  title: Overlays for the Kibana API document
+  version: 0.0.1
+actions:
+# Clean up server definitions
+  - target: '$.servers.*'
+    description: Remove all servers so we can add our own.
+    remove: true
+  - target: '$.servers'
+    description: Add server into the now empty server array.
+    update:
+      - url: https://{kibana_url}
+        variables:
+          kibana_url:
+            default: <KIBANA_URL>
+# Mark all operations as beta
+  - target: "$.paths[*]['get','put','post','delete','options','head','patch','trace']"
+    description: Add x-beta
+    update:
+      x-beta: true
+# Add some tag descriptions and displayNames
+  - target: '$.tags[?(@.name=="alerting")]'
+    description: Change tag description and displayName
+    update:
+      description: >
+        Alerting enables you to define rules, which detect complex conditions within your data.
+        When a condition is met, the rule tracks it as an alert and runs the actions that are defined in the rule. 
+        Actions typically involve the use of connectors to interact with Kibana services or third party integrations.
+      externalDocs:
+        description: Alerting documentation
+        url: https://www.elastic.co/docs/current/serverless/rules
+      x-displayName: "Alerting"
+  - target: '$.tags[?(@.name=="streams")]'
+    description: Change tag description and displayName
+    update:
+      description: >
+        Streams is a new and experimental way to manage your data in Kibana. The API is currently not considered stable and can change at any point.
+      x-displayName: "Streams"
+  - target: '$.tags[?(@.name=="connectors")]'
+    description: Change tag description and displayName
+    update:
+      description: >
+        Connectors provide a central place to store connection information for services and integrations with Elastic or third party systems.
+        Alerting rules can use connectors to run actions when rule conditions are met.
+      externalDocs:
+        description: Connector documentation
+        url: https://www.elastic.co/docs/current/serverless/action-connectors
+      x-displayName: "Connectors"
+  - target: '$.tags[?(@.name=="data views")]'
+    description: Change displayName
+    update:
+      x-displayName: "Data views"
+  - target: '$.tags[?(@.name=="ml")]'
+    description: Change displayName
+    update:
+      x-displayName: "Machine learning"
+  - target: '$.tags[?(@.name=="roles")]'
+    description: Change displayName and description
+    update:
+      x-displayName: "Roles"
+      description: Manage the roles that grant Elasticsearch and Kibana privileges.
+      externalDocs:
+        description: Kibana role management
+        url: https://www.elastic.co/guide/en/kibana/master/kibana-role-management.html
+  - target: '$.tags[?(@.name=="slo")]'
+    description: Change displayName
+    update:
+      x-displayName: "Service level objectives"
+  - target: '$.tags[?(@.name=="spaces")]'
+    description: Change displayName
+    update:
+      x-displayName: "Spaces"
+      description: Manage your Kibana spaces.
+  - target: '$.tags[?(@.name=="system")]'
+    description: Change displayName and description
+    update:
+      x-displayName: "System"
+      description: >
+        Get information about the system status, resource usage, and installed plugins.
+# Remove extra tags from operations
+  - target: "$.paths[*][*].tags[1:]"
+    description: Remove all but first tag from operations
+    remove: true

oas_docs/overlays/kibana.overlays.yaml

@@ -47,6 +47,12 @@ actions:
         description: Alerting documentation
         url: https://www.elastic.co/guide/en/kibana/8.x/alerting-getting-started.html
       x-displayName: "Alerting"
+  - target: '$.tags[?(@.name=="streams")]'
+    description: Change tag description and displayName
+    update:
+      description: >
+        Streams is a new and experimental way to manage your data in Kibana (currently experimental - expect changes).
+      x-displayName: "Streams"
   - target: '$.tags[?(@.name=="cases")]'
     description: Change tag description and displayName
     update:

src/platform/packages/shared/kbn-server-route-repository/src/register_routes.ts

@@ -169,6 +169,8 @@ export function registerRoutes<TDependencies extends Record<string, any>>({
       router.versioned[method]({
         path: pathname,
         access,
+        summary: options.summary,
+        description: options.description,
         // @ts-expect-error we are essentially calling multiple methods at the same type so TS gets confused
         options: omit(options, 'access', 'description', 'summary', 'deprecated', 'discontinued'),
         security,

x-pack/platform/plugins/shared/streams/server/routes/create_server_route.ts

@@ -20,6 +20,10 @@ export const createServerRoute: CreateServerRouteFactory<
 > = ({ handler, ...config }) => {
   return createPlainStreamsServerRoute({
     ...config,
+    options: {
+      ...config.options,
+      tags: [...(config.options?.tags ?? []), 'oas-tag:streams'],
+    },
     handler: (options) => {
       return handler(options).catch((error) => {
         if (error instanceof StatusError || error instanceof errors.ResponseError) {

x-pack/platform/plugins/shared/streams/server/routes/dashboards/route.ts

@@ -48,9 +48,15 @@ function sanitizeDashboardAsset(asset: DashboardAsset): SanitizedDashboardAsset
 }
 
 const listDashboardsRoute = createServerRoute({
-  endpoint: 'GET /api/streams/{name}/dashboards',
+  endpoint: 'GET /api/streams/{name}/dashboards 2023-10-31',
   options: {
-    access: 'internal',
+    access: 'public',
+    summary: 'Get stream dashboards',
+    description:
+      'Fetches all dashboards linked to a stream that are visible to the current user in the current space.',
+    availability: {
+      stability: 'experimental',
+    },
   },
   params: z.object({
     path: z.object({
@@ -90,9 +96,15 @@ const listDashboardsRoute = createServerRoute({
 });
 
 const linkDashboardRoute = createServerRoute({
-  endpoint: 'PUT /api/streams/{name}/dashboards/{dashboardId}',
+  endpoint: 'PUT /api/streams/{name}/dashboards/{dashboardId} 2023-10-31',
   options: {
-    access: 'internal',
+    access: 'public',
+    summary: 'Link a dashboard to a stream',
+    description:
+      'Links a dashboard to a stream. Noop if the dashboard is already linked to the stream.',
+    availability: {
+      stability: 'experimental',
+    },
   },
   security: {
     authz: {
@@ -131,9 +143,15 @@ const linkDashboardRoute = createServerRoute({
 });
 
 const unlinkDashboardRoute = createServerRoute({
-  endpoint: 'DELETE /api/streams/{name}/dashboards/{dashboardId}',
+  endpoint: 'DELETE /api/streams/{name}/dashboards/{dashboardId} 2023-10-31',
   options: {
-    access: 'internal',
+    access: 'public',
+    summary: 'Unlink a dashboard from a stream',
+    description:
+      'Unlinks a dashboard from a stream. Noop if the dashboard is not linked to the stream.',
+    availability: {
+      stability: 'experimental',
+    },
   },
   security: {
     authz: {
@@ -171,7 +189,7 @@ const unlinkDashboardRoute = createServerRoute({
 });
 
 const suggestDashboardsRoute = createServerRoute({
-  endpoint: 'POST /api/streams/{name}/dashboards/_suggestions',
+  endpoint: 'POST /internal/streams/{name}/dashboards/_suggestions',
   options: {
     access: 'internal',
   },
@@ -224,9 +242,15 @@ const dashboardSchema = z.object({
 });
 
 const bulkDashboardsRoute = createServerRoute({
-  endpoint: `POST /api/streams/{name}/dashboards/_bulk`,
+  endpoint: `POST /api/streams/{name}/dashboards/_bulk 2023-10-31`,
   options: {
-    access: 'internal',
+    access: 'public',
+    summary: 'Bulk update dashboards',
+    description:
+      'Bulk update dashboards linked to a stream. Can link new dashboards and delete existing ones.',
+    availability: {
+      stability: 'experimental',
+    },
   },
   security: {
     authz: {

x-pack/platform/plugins/shared/streams/server/routes/index.ts

@@ -5,27 +5,35 @@
  * 2.0.
  */
 
-import { esqlRoutes } from './esql/route';
+import { internalEsqlRoutes } from './internal/esql/route';
 import { dashboardRoutes } from './dashboards/route';
 import { crudRoutes } from './streams/crud/route';
 import { enablementRoutes } from './streams/enablement/route';
 import { managementRoutes } from './streams/management/route';
-import { schemaRoutes } from './streams/schema/route';
-import { processingRoutes } from './streams/processing/route';
+import { internalSchemaRoutes } from './internal/streams/schema/route';
+import { internalProcessingRoutes } from './internal/streams/processing/route';
 import { ingestRoutes } from './streams/ingest/route';
-import { lifecycleRoutes } from './streams/lifecycle/route';
+import { internalLifecycleRoutes } from './internal/streams/lifecycle/route';
 import { groupRoutes } from './streams/group/route';
+import { internalDashboardRoutes } from './internal/dashboards/route';
+import { internalCrudRoutes } from './internal/streams/crud/route';
+import { internalManagementRoutes } from './internal/streams/management/route';
 
 export const streamsRouteRepository = {
-  ...esqlRoutes,
+  // internal APIs
+  ...internalEsqlRoutes,
+  ...internalDashboardRoutes,
+  ...internalCrudRoutes,
+  ...internalManagementRoutes,
+  ...internalSchemaRoutes,
+  ...internalLifecycleRoutes,
+  ...internalProcessingRoutes,
+  // public APIs
   ...dashboardRoutes,
   ...crudRoutes,
   ...enablementRoutes,
   ...managementRoutes,
-  ...schemaRoutes,
-  ...processingRoutes,
   ...ingestRoutes,
-  ...lifecycleRoutes,
   ...groupRoutes,
 };
 

x-pack/platform/plugins/shared/streams/server/routes/internal/dashboards/route.ts

@@ -0,0 +1,76 @@
+/*
+ * 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; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { z } from '@kbn/zod';
+import { DashboardAsset } from '../../../../common/assets';
+import { createServerRoute } from '../../create_server_route';
+import { SanitizedDashboardAsset } from '../../dashboards/route';
+
+export interface SuggestDashboardResponse {
+  suggestions: SanitizedDashboardAsset[];
+}
+
+function sanitizeDashboardAsset(asset: DashboardAsset): SanitizedDashboardAsset {
+  return {
+    id: asset.assetId,
+    label: asset.label,
+    tags: asset.tags,
+  };
+}
+
+const suggestDashboardsRoute = createServerRoute({
+  endpoint: 'POST /internal/streams/{name}/dashboards/_suggestions',
+  options: {
+    access: 'internal',
+  },
+  security: {
+    authz: {
+      enabled: false,
+      reason:
+        'This API delegates security to the currently logged in user and their Elasticsearch permissions.',
+    },
+  },
+  params: z.object({
+    path: z.object({
+      name: z.string(),
+    }),
+    query: z.object({
+      query: z.string(),
+    }),
+    body: z.object({
+      tags: z.optional(z.array(z.string())),
+    }),
+  }),
+  handler: async ({ params, request, getScopedClients }): Promise<SuggestDashboardResponse> => {
+    const { assetClient, streamsClient } = await getScopedClients({ request });
+
+    await streamsClient.ensureStream(params.path.name);
+
+    const {
+      query: { query },
+      body: { tags },
+    } = params;
+
+    const suggestions = (
+      await assetClient.getSuggestions({
+        assetTypes: ['dashboard'],
+        query,
+        tags,
+      })
+    ).assets.map((asset) => {
+      return sanitizeDashboardAsset(asset as DashboardAsset);
+    });
+
+    return {
+      suggestions,
+    };
+  },
+});
+
+export const internalDashboardRoutes = {
+  ...suggestDashboardsRoute,
+};

x-pack/platform/plugins/shared/streams/server/routes/esql/route.ts → x-pack/platform/plugins/shared/streams/server/routes/internal/esql/route.ts

@@ -8,7 +8,7 @@
 import { UnparsedEsqlResponse, createTracedEsClient } from '@kbn/traced-es-client';
 import { z } from '@kbn/zod';
 import { isNumber } from 'lodash';
-import { createServerRoute } from '../create_server_route';
+import { createServerRoute } from '../../create_server_route';
 import { excludeFrozenQuery, kqlQuery, rangeQuery } from './query_helpers';
 
 export const executeEsqlRoute = createServerRoute({
@@ -67,6 +67,6 @@ export const executeEsqlRoute = createServerRoute({
   },
 });
 
-export const esqlRoutes = {
+export const internalEsqlRoutes = {
   ...executeEsqlRoute,
 };