[Experimental] Generate CRUD REST APIs for plugins using Content Management

package.json

@@ -210,6 +210,7 @@
     "@kbn/config-mocks": "link:packages/kbn-config-mocks",
     "@kbn/config-schema": "link:packages/kbn-config-schema",
     "@kbn/console-plugin": "link:src/plugins/console",
+    "@kbn/content-management-api": "link:packages/kbn-content-management-api",
     "@kbn/content-management-content-editor": "link:packages/content-management/content_editor",
     "@kbn/content-management-examples-plugin": "link:examples/content_management_examples",
     "@kbn/content-management-plugin": "link:src/plugins/content_management",

packages/core/http/core-http-router-server-internal/src/versioned_router/core_versioned_route.ts

@@ -28,7 +28,6 @@ import type { CoreVersionedRouter } from './core_versioned_router';
 
 import { validate } from './validate';
 import {
-  isAllowedPublicVersion,
   isValidRouteVersion,
   hasQueryVersion,
   readVersion,
@@ -220,12 +219,12 @@ export class CoreVersionedRoute implements VersionedRoute {
   private validateVersion(version: string) {
     // We do an additional check here while we only have a single allowed public version
     // for all public Kibana HTTP APIs
-    if (this.router.isDev && this.isPublic) {
-      const message = isAllowedPublicVersion(version);
-      if (message) {
-        throw new Error(message);
-      }
-    }
+    // if (this.router.isDev && this.isPublic) {
+    //   const message = isAllowedPublicVersion(version);
+    //   if (message) {
+    //     throw new Error(message);
+    //   }
+    // }
 
     const message = isValidRouteVersion(this.isPublic, version);
     if (message) {

packages/kbn-content-management-api/README.md

@@ -0,0 +1,4 @@
+# Content management API factory
+
+Utilities to easily create APIs for CRUD operations.
+

packages/kbn-content-management-api/index.ts

@@ -0,0 +1,10 @@
+/*
+ * 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 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 or the Server
+ * Side Public License, v 1.
+ */
+
+export { registerAPIRoutes } from './src/register_routes';
+export { contentManagementApiVersions } from './src/constants';

packages/kbn-content-management-api/jest.config.js

@@ -0,0 +1,13 @@
+/*
+ * 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 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 or the Server
+ * Side Public License, v 1.
+ */
+
+module.exports = {
+  preset: '@kbn/test',
+  rootDir: '../..',
+  roots: ['<rootDir>/packages/kbn-content-management-api'],
+};

packages/kbn-content-management-api/kibana.jsonc

@@ -0,0 +1,5 @@
+{
+  "type": "shared-common",
+  "id": "@kbn/content-management-api",
+  "owner": "@elastic/kibana-presentation"
+}

packages/kbn-content-management-api/src/constants.ts

@@ -0,0 +1,35 @@
+/*
+ * 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 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 or the Server
+ * Side Public License, v 1.
+ */
+
+import { schema } from '@kbn/config-schema';
+
+export const contentManagementApiVersions = {
+  '2023-10-31': '2023-10-31',
+} as const;
+
+export const baseGetSchema = schema.object({
+  id: schema.string(),
+  type: schema.string(),
+  references: schema.arrayOf(
+    schema.object({
+      name: schema.string(),
+      type: schema.string(),
+      id: schema.string(),
+    }),
+    { defaultValue: [] }
+  ),
+  namespaces: schema.maybe(schema.arrayOf(schema.string())),
+  updatedAt: schema.maybe(schema.string()),
+  updatedBy: schema.maybe(schema.string()),
+  error: schema.maybe(schema.string()),
+  createdAt: schema.maybe(schema.string()),
+  createdBy: schema.maybe(schema.string()),
+  managed: schema.maybe(schema.boolean()),
+  version: schema.maybe(schema.string()),
+  attributes: schema.maybe(schema.any()),
+});

packages/kbn-content-management-api/src/register_routes.ts

@@ -0,0 +1,244 @@
+/*
+ * 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 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 or the Server
+ * Side Public License, v 1.
+ */
+
+import { ObjectType, Props, schema } from '@kbn/config-schema';
+import { type ContentManagementServerSetup } from '@kbn/content-management-plugin/server';
+import { VersionedRouteResponseValidation } from '@kbn/core-http-server';
+import { HttpServiceSetup } from '@kbn/core/server';
+import { type UsageCounter } from '@kbn/usage-collection-plugin/server';
+import { baseGetSchema, contentManagementApiVersions } from './constants';
+import { ContentManagementApiVersionsType } from './types';
+
+interface RegisterAPIRoutesArgs<P extends Props> {
+  http: HttpServiceSetup;
+  contentManagement: ContentManagementServerSetup;
+  appName: string;
+  contentId: string;
+  getSchemas: () => Record<
+    ContentManagementApiVersionsType,
+    { schema: ObjectType<P>; validation?: VersionedRouteResponseValidation }
+  >;
+  getTransforms: () => Record<
+    ContentManagementApiVersionsType,
+    { inTransform?: (data: unknown) => unknown; outTransform?: (data: unknown) => unknown }
+  >;
+  restCounter?: UsageCounter;
+}
+
+function recursiveSortObjectByKeys(obj: unknown): unknown {
+  if (typeof obj !== 'object' || obj === null) return obj;
+  if (Array.isArray(obj)) {
+    return obj.map(recursiveSortObjectByKeys);
+  }
+  return Object.keys(obj)
+    .sort()
+    .reduce((acc, key) => {
+      acc[key] = recursiveSortObjectByKeys(obj[key]);
+      return acc;
+    }, {} as Record<string, unknown>);
+}
+
+export function registerAPIRoutes<P extends Props>({
+  http,
+  contentManagement,
+  appName,
+  contentId,
+  getSchemas,
+  getTransforms,
+  restCounter,
+}: RegisterAPIRoutesArgs<P>) {
+  const { versioned: versionedRouter } = http.createRouter();
+
+  // TODO add usage collection
+
+  // TODO add authorization checks
+
+  // Create API route
+  const createRoute = versionedRouter.post({
+    path: `/api/${appName}/${contentId}/{id?}`,
+    access: 'public',
+    description: `Create an item of type ${contentId}.`,
+  });
+
+  for (const version of Object.values(contentManagementApiVersions)) {
+    createRoute.addVersion(
+      {
+        version,
+        validate: {
+          request: {
+            params: schema.object({
+              id: schema.maybe(schema.string()),
+            }),
+            query: schema.object({
+              overwrite: schema.boolean({ defaultValue: false }),
+            }),
+            body: getSchemas()[version].schema,
+          },
+          response: {
+            200: {
+              body: () =>
+                baseGetSchema.extends({
+                  attributes: getSchemas()[version].schema,
+                }),
+            },
+          },
+        },
+      },
+      async (ctx, req, res) => {
+        const { id } = req.params;
+        const { overwrite } = req.query;
+        const client = contentManagement.contentClient
+          .getForRequest({ request: req, requestHandlerContext: ctx })
+          .for(contentId);
+        let result;
+        try {
+          ({
+            result: { item: result },
+          } = await client.create(req.body, { id, overwrite }));
+        } catch (e) {
+          // TODO do some error handling
+          throw e;
+        }
+
+        const body = recursiveSortObjectByKeys(result);
+        return res.ok({ body });
+      }
+    );
+  }
+
+  // Update API route
+
+  const updateRoute = versionedRouter.put({
+    path: `/api/${appName}/${contentId}/{id}`,
+    access: 'public',
+    description: `Update an item of type ${contentId}.`,
+  });
+
+  for (const version of Object.values(contentManagementApiVersions)) {
+    updateRoute.addVersion(
+      {
+        version,
+        validate: {
+          request: {
+            params: schema.object({
+              id: schema.string(),
+            }),
+            body: getSchemas()[version].schema,
+          },
+          response: {
+            200: {
+              body: () =>
+                baseGetSchema.extends({
+                  attributes: getSchemas()[version].schema,
+                }),
+            },
+          },
+        },
+      },
+      async (ctx, req, res) => {
+        const client = contentManagement.contentClient
+          .getForRequest({ request: req, requestHandlerContext: ctx })
+          .for(contentId);
+        let result;
+        try {
+          ({
+            result: { item: result },
+          } = await client.update(req.params.id, req.body));
+        } catch (e) {
+          // TODO do some error handling
+          throw e;
+        }
+
+        const body = recursiveSortObjectByKeys(result);
+        return res.ok({ body });
+      }
+    );
+  }
+
+  // Get API route
+  const getRoute = versionedRouter.get({
+    path: `/api/${appName}/${contentId}/{id}`,
+    access: 'public',
+    description: `Get an item of type ${contentId}.`,
+  });
+
+  for (const version of Object.values(contentManagementApiVersions)) {
+    getRoute.addVersion(
+      {
+        version,
+        validate: {
+          request: {
+            params: schema.object({
+              id: schema.string(),
+            }),
+          },
+          response: {
+            200: {
+              body: () =>
+                baseGetSchema.extends({
+                  attributes: getSchemas()[version].schema,
+                }),
+            },
+          },
+        },
+      },
+      async (ctx, req, res) => {
+        const client = contentManagement.contentClient
+          .getForRequest({ request: req, requestHandlerContext: ctx })
+          .for(contentId);
+        let result;
+        try {
+          ({
+            result: { item: result },
+          } = await client.get(req.params.id));
+        } catch (e) {
+          // TODO do some error handling
+          throw e;
+        }
+
+        const body = recursiveSortObjectByKeys(result);
+        return res.ok({ body });
+      }
+    );
+  }
+
+  // Delete API route
+  const deleteRoute = versionedRouter.delete({
+    path: `/api/${appName}/${contentId}/{id}`,
+    access: 'public',
+    description: `Delete an item of type ${contentId}.`,
+  });
+
+  for (const version of Object.values(contentManagementApiVersions)) {
+    deleteRoute.addVersion(
+      {
+        version,
+        validate: {
+          request: {
+            params: schema.object({
+              id: schema.string(),
+            }),
+          },
+        },
+      },
+      async (ctx, req, res) => {
+        const client = contentManagement.contentClient
+          .getForRequest({ request: req, requestHandlerContext: ctx })
+          .for(contentId);
+        try {
+          await client.delete(req.params.id);
+        } catch (e) {
+          // TODO do some error handling
+          throw e;
+        }
+
+        return res.ok();
+      }
+    );
+  }
+}

packages/kbn-content-management-api/src/types.ts

@@ -0,0 +1,12 @@
+/*
+ * 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 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 or the Server
+ * Side Public License, v 1.
+ */
+
+import { contentManagementApiVersions } from './constants';
+
+export type ContentManagementApiVersionsType =
+  typeof contentManagementApiVersions[keyof typeof contentManagementApiVersions];

packages/kbn-content-management-api/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "target/types",
+    "types": [
+      "jest",
+      "node",
+      "react"
+    ]
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+  ],
+  "exclude": [
+    "target/**/*"
+  ],
+  "kbn_references": [
+    "@kbn/content-management-plugin",
+    "@kbn/config-schema",
+    "@kbn/core-saved-objects-api-server",
+    "@kbn/config-schema",
+    "@kbn/object-versioning",
+    "@kbn/logging",
+    "@kbn/logging-mocks",
+    "@kbn/core",
+  ]
+}