[ResponseOps][MaintenanceWindow] Public maintenance window API (elastic#216756)

Closes elastic#198685

## Summary

This PR creates a public Maintenance Window API.

The work was done on a feature branch over multiple separate PRs. Here
we will merge the feature branch into `main`.
- elastic#209734
- elastic#213694
- elastic#214747
- elastic#213771

The [documentation PR](elastic#212377)
still needs to be merged.

## Release Notes

Publish new public APIs for the Maintenance Window.

---------

Co-authored-by: kibanamachine <[email protected]>
Co-authored-by: lcawl <[email protected]>

Author: 3 people

.buildkite/scripts/steps/checks/capture_oas_snapshot.sh

@@ -19,7 +19,8 @@ cmd="node scripts/capture_oas_snapshot \
   --include-path /api/fleet \
   --include-path /api/dashboards \
   --include-path /api/saved_objects/_import \
-  --include-path /api/saved_objects/_export"
+  --include-path /api/saved_objects/_export \
+  --include-path /api/alerting/maintenance_window"
 if is_pr && ! is_auto_commit_disabled; then
   cmd="$cmd --update"
 fi

oas_docs/overlays/kibana.overlays.shared.yaml

@@ -4,7 +4,17 @@ info:
   title: Overlays that are applicable to both serverless and non-serverless documentas
   version: 0.0.1
 actions:
-# Add some tag descriptions and displayNames
+  # Add some tag descriptions and displayNames
+  - target: '$.tags[?(@.name=="maintenance-window")]'
+    description: Change tag description and displayName
+    update:
+      description: >
+        You can schedule single or recurring maintenance windows to temporarily reduce rule notifications.
+        For example, a maintenance window prevents false alarms during planned outages.
+      externalDocs:
+        description: Maintenance window documentation
+        url: https://www.elastic.co/docs/explore-analyze/alerts-cases/alerts/maintenance-windows
+      x-displayName: 'Maintenance windows'
   - target: '$.tags[?(@.name=="alerting")]'
     description: Change tag description and displayName
     update:
@@ -15,7 +25,7 @@ actions:
       externalDocs:
         description: Alerting documentation
         url: https://www.elastic.co/docs/explore-analyze/alerts-cases/alerts
-      x-displayName: "Alerting"
+      x-displayName: 'Alerting'
   - target: '$.tags[?(@.name=="cases")]'
     description: Change tag description and displayName
     update:
@@ -26,7 +36,7 @@ actions:
       externalDocs:
         description: Cases documentation
         url: https://www.elastic.co/docs/explore-analyze/alerts-cases/cases
-      x-displayName: "Cases"
+      x-displayName: 'Cases'
   - target: '$.tags[?(@.name=="connectors")]'
     description: Change tag description and displayName
     update:
@@ -36,45 +46,45 @@ actions:
       externalDocs:
         description: Connector documentation
         url: https://www.elastic.co/docs/reference/kibana/connectors-kibana
-      x-displayName: "Connectors"
-# Add some spaces API examples
+      x-displayName: 'Connectors'
+  # Add some spaces API examples
   - target: "$.paths['/api/spaces/space']['post']"
-    description: "Add example to create space API"
+    description: 'Add example to create space API'
     update:
       requestBody:
         content:
           application/json:
             examples:
               createSpaceRequest:
-                $ref: "../examples/create_space_request.yaml"
+                $ref: '../examples/create_space_request.yaml'
   - target: "$.paths['/api/spaces/space/{id}']['put']"
-    description: "Add example to update space API"
+    description: 'Add example to update space API'
     update:
       requestBody:
         content:
           application/json:
             examples:
               updateSpaceRequest:
-                $ref: "../examples/update_space_request.yaml"
+                $ref: '../examples/update_space_request.yaml'
   - target: "$.paths['/api/spaces/space/{id}']['get']"
-    description: "Add example to get space API"
+    description: 'Add example to get space API'
     update:
       responses:
         200:
           content:
             application/json:
               examples:
                 getSpaceResponseExample:
-                  $ref: "../examples/get_space_response.yaml"
+                  $ref: '../examples/get_space_response.yaml'
   - target: "$.paths['/api/spaces/space']['get']"
-    description: "Add example to get all spaces API"
+    description: 'Add example to get all spaces API'
     update:
       responses:
         200:
           content:
             application/json:
               examples:
                 getSpacesResponseExample1:
-                  $ref: "../examples/get_spaces_response1.yaml"
+                  $ref: '../examples/get_spaces_response1.yaml'
                 getSpacesResponseExample2:
-                  $ref: "../examples/get_spaces_response2.yaml"
+                  $ref: '../examples/get_spaces_response2.yaml'

x-pack/platform/plugins/shared/alerting/common/index.ts

@@ -209,6 +209,9 @@ export {
 
 export const LEGACY_BASE_ALERT_API_PATH = '/api/alerts';
 export const BASE_ALERTING_API_PATH = '/api/alerting';
+export const BASE_MAINTENANCE_WINDOW_API_PATH = '/api/maintenance_window';
+
+// Internal
 export const INTERNAL_BASE_ALERTING_API_PATH = '/internal/alerting' as const;
 export const INTERNAL_ALERTING_SNOOZE_RULE =
   `${INTERNAL_BASE_ALERTING_API_PATH}/rule/{id}/_snooze` as const;
@@ -242,6 +245,14 @@ export const INTERNAL_ALERTING_GAPS_GET_SUMMARY_BY_RULE_IDS_API_PATH =
 export const INTERNAL_ALERTING_GAPS_FILL_BY_ID_API_PATH =
   `${INTERNAL_ALERTING_GAPS_API_PATH}/_fill_by_id` as const;
 
+// External
+export const ARCHIVE_MAINTENANCE_WINDOW_API_PATH = `${BASE_MAINTENANCE_WINDOW_API_PATH}/{id}/_archive`;
+export const UNARCHIVE_MAINTENANCE_WINDOW_API_PATH = `${BASE_MAINTENANCE_WINDOW_API_PATH}/{id}/_unarchive`;
+export const CREATE_MAINTENANCE_WINDOW_API_PATH = BASE_MAINTENANCE_WINDOW_API_PATH;
+export const GET_MAINTENANCE_WINDOW_API_PATH = `${BASE_MAINTENANCE_WINDOW_API_PATH}/{id}`;
+export const UPDATE_MAINTENANCE_WINDOW_API_PATH = `${BASE_MAINTENANCE_WINDOW_API_PATH}/{id}`;
+export const DELETE_MAINTENANCE_WINDOW_API_PATH = `${BASE_MAINTENANCE_WINDOW_API_PATH}/{id}`;
+
 export const ALERTING_FEATURE_ID = 'alerts';
 export const MONITORING_HISTORY_LIMIT = 200;
 export const ENABLE_MAINTENANCE_WINDOWS = true;

x-pack/platform/plugins/shared/alerting/common/routes/maintenance_window/external/apis/archive/index.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
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+export { archiveMaintenanceWindowRequestParamsSchema } from './schemas/latest';
+export type {
+  ArchiveMaintenanceWindowRequestParams,
+  ArchiveMaintenanceWindowResponse,
+} from './types/latest';
+
+export { archiveMaintenanceWindowRequestParamsSchema as archiveMaintenanceWindowRequestParamsSchemaV1 } from './schemas/v1';
+
+export type {
+  ArchiveMaintenanceWindowRequestParams as ArchiveMaintenanceWindowRequestParamsV1,
+  ArchiveMaintenanceWindowResponse as ArchiveMaintenanceWindowResponseV1,
+} from './types/latest';

x-pack/platform/plugins/shared/alerting/common/routes/maintenance_window/external/apis/archive/schemas/latest.ts

@@ -0,0 +1,8 @@
+/*
+ * 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.
+ */
+
+export { archiveMaintenanceWindowRequestParamsSchema } from './v1';

x-pack/platform/plugins/shared/alerting/common/routes/maintenance_window/external/apis/archive/schemas/v1.ts

@@ -0,0 +1,16 @@
+/*
+ * 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 { schema } from '@kbn/config-schema';
+
+export const archiveMaintenanceWindowRequestParamsSchema = schema.object({
+  id: schema.string({
+    meta: {
+      description: 'The identifier for the maintenance window to be archived.',
+    },
+  }),
+});

x-pack/platform/plugins/shared/alerting/common/routes/maintenance_window/external/apis/archive/types/latest.ts

@@ -0,0 +1,8 @@
+/*
+ * 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.
+ */
+
+export type { ArchiveMaintenanceWindowRequestParams, ArchiveMaintenanceWindowResponse } from './v1';

x-pack/platform/plugins/shared/alerting/common/routes/maintenance_window/external/apis/archive/types/v1.ts

@@ -0,0 +1,18 @@
+/*
+ * 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 type { TypeOf } from '@kbn/config-schema';
+import type { MaintenanceWindowResponseV1 } from '../../../response';
+import type { archiveMaintenanceWindowRequestParamsSchemaV1 } from '..';
+
+export type ArchiveMaintenanceWindowRequestParams = TypeOf<
+  typeof archiveMaintenanceWindowRequestParamsSchemaV1
+>;
+
+export interface ArchiveMaintenanceWindowResponse {
+  body: MaintenanceWindowResponseV1;
+}

x-pack/platform/plugins/shared/alerting/common/routes/maintenance_window/external/apis/create/index.ts

@@ -0,0 +1,18 @@
+/*
+ * 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.
+ */
+
+export { createMaintenanceWindowRequestBodySchema } from './schemas/latest';
+export type {
+  CreateMaintenanceWindowRequestBody,
+  CreateMaintenanceWindowResponse,
+} from './types/latest';
+
+export { createMaintenanceWindowRequestBodySchema as createMaintenanceWindowRequestBodySchemaV1 } from './schemas/v1';
+export type {
+  CreateMaintenanceWindowRequestBody as CreateMaintenanceWindowRequestBodyV1,
+  CreateMaintenanceWindowResponse as CreateMaintenanceWindowResponseV1,
+} from './types/v1';

x-pack/platform/plugins/shared/alerting/common/routes/maintenance_window/external/apis/create/schemas/latest.ts

@@ -0,0 +1,8 @@
+/*
+ * 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.
+ */
+
+export { createMaintenanceWindowRequestBodySchema } from './v1';