[ML] Transforms: API schemas and integration tests (#75164)

- Adds schema definitions to transform API endpoints and adds API integration tests.
- The type definitions based on the schema definitions can be used on the client side too.
- Adds apidoc documentation.

Author: walterra

x-pack/plugins/ml/common/index.ts

@@ -0,0 +1,7 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+export { SearchResponse7 } from './types/es_client';

x-pack/plugins/ml/common/types/es_client.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+import { SearchResponse, ShardsResponse } from 'elasticsearch';
+
+// The types specified in `@types/elasticsearch` are out of date and still have `total: number`.
+interface SearchResponse7Hits<T> {
+  hits: SearchResponse<T>['hits']['hits'];
+  max_score: number;
+  total: {
+    value: number;
+    relation: string;
+  };
+}
+export interface SearchResponse7<T = any> {
+  took: number;
+  timed_out: boolean;
+  _scroll_id?: string;
+  _shards: ShardsResponse;
+  hits: SearchResponse7Hits<T>;
+  aggregations?: any;
+}

x-pack/plugins/ml/public/application/components/data_grid/index.ts

@@ -19,7 +19,6 @@ export {
   DataGridItem,
   EsSorting,
   RenderCellValue,
-  SearchResponse7,
   UseDataGridReturnType,
   UseIndexDataReturnType,
 } from './types';

x-pack/plugins/ml/public/application/components/data_grid/types.ts

@@ -5,7 +5,6 @@
  */
 
 import { Dispatch, SetStateAction } from 'react';
-import { SearchResponse } from 'elasticsearch';
 
 import { EuiDataGridPaginationProps, EuiDataGridSorting, EuiDataGridColumn } from '@elastic/eui';
 
@@ -43,16 +42,6 @@ export type EsSorting = Dictionary<{
   order: 'asc' | 'desc';
 }>;
 
-// The types specified in `@types/elasticsearch` are out of date and still have `total: number`.
-export interface SearchResponse7 extends SearchResponse<any> {
-  hits: SearchResponse<any>['hits'] & {
-    total: {
-      value: number;
-      relation: string;
-    };
-  };
-}
-
 export interface UseIndexDataReturnType
   extends Pick<
     UseDataGridReturnType,

x-pack/plugins/ml/public/application/data_frame_analytics/common/get_index_data.ts

@@ -4,9 +4,10 @@
  * you may not use this file except in compliance with the Elastic License.
  */
 
+import type { SearchResponse7 } from '../../../../common/types/es_client';
 import { extractErrorMessage } from '../../../../common/util/errors';
 
-import { EsSorting, SearchResponse7, UseDataGridReturnType } from '../../components/data_grid';
+import { EsSorting, UseDataGridReturnType } from '../../components/data_grid';
 import { ml } from '../../services/ml_api_service';
 
 import { isKeywordAndTextType } from '../common/fields';

x-pack/plugins/ml/public/application/data_frame_analytics/pages/analytics_creation/hooks/use_index_data.ts

@@ -22,9 +22,9 @@ import {
   useDataGrid,
   useRenderCellValue,
   EsSorting,
-  SearchResponse7,
   UseIndexDataReturnType,
 } from '../../../../components/data_grid';
+import type { SearchResponse7 } from '../../../../../../common/types/es_client';
 import { extractErrorMessage } from '../../../../../../common/util/errors';
 import { INDEX_STATUS } from '../../../common/analytics';
 import { ml } from '../../../../services/ml_api_service';

x-pack/plugins/transform/common/api_schemas/audit_messages.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+import { TransformMessage } from '../types/messages';
+
+export type GetTransformsAuditMessagesResponseSchema = TransformMessage[];

x-pack/plugins/transform/common/api_schemas/common.ts

@@ -0,0 +1,48 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+import { schema, TypeOf } from '@kbn/config-schema';
+
+import { TRANSFORM_STATE } from '../constants';
+
+export const transformIdsSchema = schema.arrayOf(
+  schema.object({
+    id: schema.string(),
+  })
+);
+
+export type TransformIdsSchema = TypeOf<typeof transformIdsSchema>;
+
+export const transformStateSchema = schema.oneOf([
+  schema.literal(TRANSFORM_STATE.ABORTING),
+  schema.literal(TRANSFORM_STATE.FAILED),
+  schema.literal(TRANSFORM_STATE.INDEXING),
+  schema.literal(TRANSFORM_STATE.STARTED),
+  schema.literal(TRANSFORM_STATE.STOPPED),
+  schema.literal(TRANSFORM_STATE.STOPPING),
+]);
+
+export const indexPatternTitleSchema = schema.object({
+  /** Title of the index pattern for which to return stats. */
+  indexPatternTitle: schema.string(),
+});
+
+export type IndexPatternTitleSchema = TypeOf<typeof indexPatternTitleSchema>;
+
+export const transformIdParamSchema = schema.object({
+  transformId: schema.string(),
+});
+
+export type TransformIdParamSchema = TypeOf<typeof transformIdParamSchema>;
+
+export interface ResponseStatus {
+  success: boolean;
+  error?: any;
+}
+
+export interface CommonResponseStatusSchema {
+  [key: string]: ResponseStatus;
+}

x-pack/plugins/transform/common/api_schemas/delete_transforms.ts

@@ -0,0 +1,37 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+import { schema, TypeOf } from '@kbn/config-schema';
+
+import { transformStateSchema, ResponseStatus } from './common';
+
+export const deleteTransformsRequestSchema = schema.object({
+  /**
+   * Delete Transform & Destination Index
+   */
+  transformsInfo: schema.arrayOf(
+    schema.object({
+      id: schema.string(),
+      state: transformStateSchema,
+    })
+  ),
+  deleteDestIndex: schema.maybe(schema.boolean()),
+  deleteDestIndexPattern: schema.maybe(schema.boolean()),
+  forceDelete: schema.maybe(schema.boolean()),
+});
+
+export type DeleteTransformsRequestSchema = TypeOf<typeof deleteTransformsRequestSchema>;
+
+export interface DeleteTransformStatus {
+  transformDeleted: ResponseStatus;
+  destIndexDeleted?: ResponseStatus;
+  destIndexPatternDeleted?: ResponseStatus;
+  destinationIndex?: string | undefined;
+}
+
+export interface DeleteTransformsResponseSchema {
+  [key: string]: DeleteTransformStatus;
+}

x-pack/plugins/transform/common/api_schemas/field_histograms.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License;
+ * you may not use this file except in compliance with the Elastic License.
+ */
+
+import { schema, TypeOf } from '@kbn/config-schema';
+
+export const fieldHistogramsRequestSchema = schema.object({
+  /** Query to match documents in the index. */
+  query: schema.any(),
+  /** The fields to return histogram data. */
+  fields: schema.arrayOf(schema.any()),
+  /** Number of documents to be collected in the sample processed on each shard, or -1 for no sampling. */
+  samplerShardSize: schema.number(),
+});
+
+export type FieldHistogramsRequestSchema = TypeOf<typeof fieldHistogramsRequestSchema>;
+export type FieldHistogramsResponseSchema = any[];