[DOCS] Improves Detections API docs content (#187224)

## Summary Resolves elastic/docs-projects#219 by improving the Detections API docs content. Adds missing and improves existing operation summaries and operation descriptions. Also addresses some of the work planned in #183702. --------- Co-authored-by: kibanamachine <[email protected]>
elastic · Jul 18, 2024 · ac5beb6 · ac5beb6
1 parent 926df56
commit ac5beb6
Show file tree

Hide file tree

Showing 34 changed files with 335 additions and 146 deletions.
diff --git a/...olution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml b/...olution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml
@@ -4,12 +4,15 @@ info:
   version: '2023-10-31'
 paths:
   /api/detection_engine/signals/assignees:
-    summary: Assigns users to alerts
     post:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: SetAlertAssignees
-      description: Assigns users to alerts.
+      summary: Assign and unassign users from detection alerts
+      description: |
+        Assign users to detection alerts, and unassign them from alerts.
+        > info
+        > You cannot add and remove the same assignee in the same request.
       requestBody:
         required: true
         content:

diff --git a/...solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml b/...solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml
@@ -8,7 +8,11 @@ paths:
       x-labels: [serverless, ess]
       operationId: ManageAlertTags
       x-codegen-enabled: true
-      summary: Manage alert tags for a one or more alerts
+      summary: Add and remove detection alert tags
+      description: |
+        And tags to detection alerts, and remove them from alerts.
+        > info
+        > You cannot add and remove the same alert tag in the same request.
       tags:
         - Alerts API
       requestBody:

diff --git a/..._solution/common/api/detection_engine/model/rule_response_actions/response_actions.gen.ts b/..._solution/common/api/detection_engine/model/rule_response_actions/response_actions.gen.ts
@@ -36,7 +36,7 @@ export const OsqueryQuery = z.object({
    */
   id: z.string(),
   /**
-   * Query to execute
+   * Query to run
    */
   query: z.string(),
   ecs_mapping: EcsMapping.optional(),

diff --git a/...tion/common/api/detection_engine/model/rule_response_actions/response_actions.schema.yaml b/...tion/common/api/detection_engine/model/rule_response_actions/response_actions.schema.yaml
@@ -34,7 +34,7 @@ components:
           description: Query ID
         query:
           type: string
-          description: Query to execute
+          description: Query to run
         ecs_mapping:
           $ref: '#/components/schemas/EcsMapping'
         version:

diff --git a/.../security_solution/common/api/detection_engine/model/rule_schema/common_attributes.gen.ts b/.../security_solution/common/api/detection_engine/model/rule_schema/common_attributes.gen.ts
@@ -99,7 +99,7 @@ export type RuleInterval = z.infer<typeof RuleInterval>;
 export const RuleInterval = z.string();
 
 /**
- * Time from which data is analyzed each time the rule executes, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).
+ * Time from which data is analyzed each time the rule runs, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).
  */
 export type RuleIntervalFrom = z.infer<typeof RuleIntervalFrom>;
 export const RuleIntervalFrom = z.string().superRefine(isValidDateMath);
@@ -454,7 +454,7 @@ export const InvestigationFields = z.object({
 });
 
 /**
- * Defines the interval on which a rule's actions are executed.
+ * Defines how often rule actions are taken.
  */
 export type RuleActionThrottle = z.infer<typeof RuleActionThrottle>;
 export const RuleActionThrottle = z.union([

diff --git a/...rity_solution/common/api/detection_engine/model/rule_schema/common_attributes.schema.yaml b/...rity_solution/common/api/detection_engine/model/rule_schema/common_attributes.schema.yaml
@@ -92,7 +92,7 @@ components:
 
     RuleIntervalFrom:
       type: string
-      description: Time from which data is analyzed each time the rule executes, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).
+      description: Time from which data is analyzed each time the rule runs, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).
       format: date-math
 
     RuleIntervalTo:
@@ -470,7 +470,7 @@ components:
         - field_names
 
     RuleActionThrottle:
-      description: Defines the interval on which a rule's actions are executed.
+      description: Defines how often rule actions are taken.
       oneOf:
         - type: string
           enum:

diff --git a/...api/detection_engine/model/rule_schema/specific_attributes/threat_match_attributes.gen.ts b/...api/detection_engine/model/rule_schema/specific_attributes/threat_match_attributes.gen.ts
@@ -19,7 +19,7 @@ import { z } from 'zod';
 import { NonEmptyString } from '../../../../model/primitives.gen';
 
 /**
- * Query to execute
+ * Query to run
  */
 export type ThreatQuery = z.infer<typeof ThreatQuery>;
 export const ThreatQuery = z.string();

diff --git a/...etection_engine/model/rule_schema/specific_attributes/threat_match_attributes.schema.yaml b/...etection_engine/model/rule_schema/specific_attributes/threat_match_attributes.schema.yaml
@@ -8,7 +8,7 @@ components:
   schemas:
     ThreatQuery:
       type: string
-      description: Query to execute
+      description: Query to run
 
     ThreatMapping:
       type: array

diff --git a/...uilt_rules_and_timelines_status/get_prebuilt_rules_and_timelines_status_route.schema.yaml b/...uilt_rules_and_timelines_status/get_prebuilt_rules_and_timelines_status_route.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [ess]
       x-codegen-enabled: true
       operationId: GetPrebuiltRulesAndTimelinesStatus
-      summary: Get the status of Elastic prebuilt rules
+      summary: Retrieve the status of prebuilt detection rules and Timelines
+      description: Retrieve the status of all Elastic prebuilt detection rules and Timelines.
       tags:
         - Prebuilt Rules API
       responses:

diff --git a/...stall_prebuilt_rules_and_timelines/install_prebuilt_rules_and_timelines_route.schema.yaml b/...stall_prebuilt_rules_and_timelines/install_prebuilt_rules_and_timelines_route.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [ess]
       x-codegen-enabled: true
       operationId: InstallPrebuiltRulesAndTimelines
-      summary: Installs all Elastic prebuilt rules and timelines
+      summary: Install prebuilt detection rules and Timelines
+      description: Install and update all Elastic prebuilt detection rules and Timelines.
       tags:
         - Prebuilt Rules API
       responses:

diff --git a/...lution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.gen.ts b/...lution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.gen.ts
@@ -241,7 +241,7 @@ export const BulkActionEditPayloadSchedule = z.object({
   type: z.literal('set_schedule'),
   value: z.object({
     /**
-     * Interval in which the rule is executed
+     * Interval in which the rule runs. For example, `"1h"` means the rule runs every hour.
      */
     interval: z.string().regex(/^[1-9]\d*[smh]$/),
     /**

diff --git a/...n/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml b/...n/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml
@@ -8,8 +8,8 @@ paths:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: PerformBulkAction
-      summary: Applies a bulk action to multiple rules
-      description: The bulk action is applied to all rules that match the filter or to the list of rules by their IDs.
+      summary: Apply a bulk action to detection rules
+      description: Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.
       tags:
         - Bulk API
       parameters:
@@ -366,7 +366,7 @@ components:
           properties:
             interval:
               type: string
-              description: Interval in which the rule is executed
+              description: Interval in which the rule runs. For example, `"1h"` means the rule runs every hour.
               pattern: '^[1-9]\d*[smh]$' # any number except zero followed by one of the suffixes 's', 'm', 'h'
               example: '1h'
             lookback:

diff --git a/...on_engine/rule_management/bulk_crud/bulk_create_rules/bulk_create_rules_route.schema.yaml b/...on_engine/rule_management/bulk_crud/bulk_create_rules/bulk_create_rules_route.schema.yaml
@@ -9,7 +9,8 @@ paths:
       x-codegen-enabled: true
       operationId: BulkCreateRules
       deprecated: true
-      description: Creates new detection rules in bulk.
+      summary: Create multiple detection rules 
+      description: Create new detection rules in bulk.
       tags:
         - Bulk API
       requestBody:

diff --git a/...on_engine/rule_management/bulk_crud/bulk_delete_rules/bulk_delete_rules_route.schema.yaml b/...on_engine/rule_management/bulk_crud/bulk_delete_rules/bulk_delete_rules_route.schema.yaml
@@ -9,7 +9,8 @@ paths:
       x-codegen-enabled: true
       operationId: BulkDeleteRules
       deprecated: true
-      description: Deletes multiple rules.
+      summary: Delete multiple detection rules
+      description: Delete detection rules in bulk.
       tags:
         - Bulk API
       requestBody:

diff --git a/...tion_engine/rule_management/bulk_crud/bulk_patch_rules/bulk_patch_rules_route.schema.yaml b/...tion_engine/rule_management/bulk_crud/bulk_patch_rules/bulk_patch_rules_route.schema.yaml
@@ -7,9 +7,10 @@ paths:
     patch:
       x-labels: [ess]
       x-codegen-enabled: true
+      summary: Patch multiple detection rules
       operationId: BulkPatchRules
       deprecated: true
-      description: Updates multiple rules using the `PATCH` method.
+      description: Update specific fields of existing detection rules using the `rule_id` or `id` field.
       tags:
         - Bulk API
       requestBody:

diff --git a/...on_engine/rule_management/bulk_crud/bulk_update_rules/bulk_update_rules_route.schema.yaml b/...on_engine/rule_management/bulk_crud/bulk_update_rules/bulk_update_rules_route.schema.yaml
@@ -9,7 +9,11 @@ paths:
       x-codegen-enabled: true
       operationId: BulkUpdateRules
       deprecated: true
-      description: Updates multiple rules using the `PUT` method.
+      summary: Update multiple detection rules
+      description: |
+        Update multiple detection rules using the `rule_id` or `id` field. The original rules are replaced, and all unspecified fields are deleted.
+        > info
+        > You cannot modify the `id` or `rule_id` values.
       tags:
         - Bulk API
       requestBody:

diff --git a/...ommon/api/detection_engine/rule_management/crud/create_rule/create_rule_route.schema.yaml b/...ommon/api/detection_engine/rule_management/crud/create_rule/create_rule_route.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: CreateRule
-      description: Create a single detection rule
+      summary: Create a detection rule
+      description: Create a new detection rule.
       tags:
         - Rules API
       requestBody:

diff --git a/...ommon/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml b/...ommon/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: DeleteRule
-      description: Deletes a single rule using the `rule_id` or `id` field.
+      summary: Delete a detection rule
+      description: Delete a detection rule using the `rule_id` or `id` field.
       tags:
         - Rules API
       parameters:

diff --git a/.../common/api/detection_engine/rule_management/crud/patch_rule/patch_rule_route.schema.yaml b/.../common/api/detection_engine/rule_management/crud/patch_rule/patch_rule_route.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: PatchRule
-      description: Patch a single rule
+      summary: Patch a detection rule
+      description: Update specific fields of an existing detection rule using the `rule_id` or `id` field.
       tags:
         - Rules API
       requestBody:

diff --git a/...on/common/api/detection_engine/rule_management/crud/read_rule/read_rule_route.schema.yaml b/...on/common/api/detection_engine/rule_management/crud/read_rule/read_rule_route.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: ReadRule
-      description: Read a single rule
+      summary: Retrieve a detection rule
+      description: Retrieve a detection rule using the `rule_id` or `id` field.
       tags:
         - Rules API
       parameters:

diff --git a/...ommon/api/detection_engine/rule_management/crud/update_rule/update_rule_route.schema.yaml b/...ommon/api/detection_engine/rule_management/crud/update_rule/update_rule_route.schema.yaml
@@ -8,7 +8,11 @@ paths:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: UpdateRule
-      description: Update a single rule
+      summary: Update a detection rule
+      description: |
+        Update a detection rule using the `rule_id` or `id` field. The original rule is replaced, and all unspecified fields are deleted.
+        > info
+        > You cannot modify the `id` or `rule_id` values.
       tags:
         - Rules API
       requestBody:

diff --git a/...n/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml b/...n/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml
@@ -4,13 +4,17 @@ info:
   version: '2023-10-31'
 paths:
   /api/detection_engine/rules/_export:
-    summary: Exports rules to an `.ndjson` file
     post:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: ExportRules
-      summary: Export rules
-      description: Exports rules to an `.ndjson` file. The following configuration items are also included in the `.ndjson` file - Actions, Exception lists. Prebuilt rules cannot be exported.
+      summary: Export detection rules
+      description: |
+        Export detection rules to an `.ndjson` file. The following configuration items are also included in the `.ndjson` file:
+        - Actions
+        - Exception lists
+        > info
+        > You cannot export prebuilt rules.
       tags:
         - Import/Export API
       parameters:

diff --git a/...ution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml b/...ution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: FindRules
-      description: Finds rules that match the given query.
+      summary: List all detection rules
+      description: Retrieve a paginated list of detection rules. By default, the first page is returned, with 20 results per page.
       tags:
         - Rules API
       parameters:

diff --git a/...n/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml b/...n/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml
@@ -4,13 +4,15 @@ info:
   version: '2023-10-31'
 paths:
   /api/detection_engine/rules/_import:
-    summary: Imports rules from an `.ndjson` file
     post:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: ImportRules
-      summary: Import rules
-      description: Imports rules from an `.ndjson` file, including actions and exception lists.
+      summary: Import detection rules
+      description: |
+        Import detection rules from an `.ndjson` file, including actions and exception lists. The request must include:
+        - The `Content-Type: multipart/form-data` HTTP header.
+        - A link to the `.ndjson` file containing the rules.
       tags:
         - Import/Export API
       requestBody:

diff --git a/...olution/common/api/detection_engine/rule_management/read_tags/read_tags_route.schema.yaml b/...olution/common/api/detection_engine/rule_management/read_tags/read_tags_route.schema.yaml
@@ -4,12 +4,12 @@ info:
   version: '2023-10-31'
 paths:
   /api/detection_engine/tags:
-    summary: Aggregates and returns rule tags
     get:
       x-labels: [ess, serverless]
       x-codegen-enabled: true
       operationId: ReadTags
-      summary: Aggregates and returns all unique tags from all rules
+      summary: List all detection rule tags
+      description: List all unique tags from all detection rules.
       tags:
         - Tags API
       responses:

diff --git a/...olution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml b/...olution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: SearchAlerts
       x-codegen-enabled: true
-      summary: Find and/or aggregate detection alerts that match the given query
+      summary: Find and/or aggregate detection alerts
+      description: Find and/or aggregate detection alerts that match the given query.
       tags:
         - Alerts API
       requestBody:

diff --git a/...ommon/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml b/...ommon/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [serverless, ess]
       operationId: SetAlertsStatus
       x-codegen-enabled: true
-      summary: Sets the status of one or more alerts
+      summary: Set a detection alert status
+      description: Set the status of one or more detection alerts.
       tags:
         - Alerts API
       requestBody:

diff --git a/...on_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml b/...on_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml
@@ -8,7 +8,10 @@ paths:
       x-labels: [ess]
       operationId: CreateAlertsMigration
       x-codegen-enabled: true
-      summary: Initiates an alerts migration
+      summary: Initiate a detection alert migration
+      description: |
+        Initiate a migration of detection alerts.
+        Migrations are initiated per index. While the process is neither destructive nor interferes with existing data, it may be resource-intensive. As such, it is recommended that you plan your migrations accordingly.
       tags:
         - Alerts migration API
       requestBody:

diff --git a/...on_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml b/...on_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml
@@ -8,11 +8,13 @@ paths:
       x-labels: [ess]
       operationId: AlertsMigrationCleanup
       x-codegen-enabled: true
-      summary: Performs alerts migration(s) cleanup
+      summary: Clean up detection alert migrations
       description: |
         Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
         the migration process. A successful migration will result in both the old and new indices being present.
-        As such, the old, orphaned index can (and likely should) be deleted. While you can delete these indices manually,
+        As such, the old, orphaned index can (and likely should) be deleted.
+        
+        While you can delete these indices manually,
         the endpoint accomplishes this task by applying a deletion policy to the relevant index, causing it to be deleted
         after 30 days. It also deletes other artifacts specific to the migration implementation.
       tags:

diff --git a/...ngine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml b/...ngine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml
@@ -8,9 +8,9 @@ paths:
       x-labels: [ess]
       operationId: FinalizeAlertsMigration
       x-codegen-enabled: true
-      summary: Finalizes alerts migration(s)
+      summary: Finalize detection alert migrations
       description: |
-        The finalization endpoint replaces the original index's alias with the successfully migrated index's alias.
+        Finalize successful migrations of detection alerts. This replaces the original index's alias with the successfully migrated index's alias.
         The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion,
         finalize it.
       tags:

diff --git a/...e/signals_migration/get_signals_migration_status/get_signals_migration_status.schema.yaml b/...e/signals_migration/get_signals_migration_status/get_signals_migration_status.schema.yaml
@@ -8,7 +8,8 @@ paths:
       x-labels: [ess]
       operationId: GetAlertsMigrationStatus
       x-codegen-enabled: true
-      summary: Returns an alerts migration status
+      summary: Retrieve the status of detection alert migrations
+      description: Retrieve indices that contain detection alerts of a particular age, along with migration information for each of those indices.
       tags:
         - Alerts migration API
       parameters: