[DOCS] Create open API specification for update rule (elastic#147407)

jennypavlova · Jan 13, 2023 · 832d129 · 832d129
1 parent 987c23b
commit 832d129
Show file tree

Hide file tree

Showing 20 changed files with 1,894 additions and 591 deletions.
diff --git a/docs/api-generated/rules/rule-apis-passthru.asciidoc b/docs/api-generated/rules/rule-apis-passthru.asciidoc
diff --git a/docs/api/alerting/delete_rule.asciidoc b/docs/api/alerting/delete_rule.asciidoc
@@ -8,6 +8,12 @@ Permanently removes a rule.
 
 WARNING: After you delete a rule, you cannot recover it.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/x-pack/plugins/alerting/docs/openapi[open API specification]. For a preview, check out <<rule-apis>>.
+====
+
 [[delete-rule-api-request]]
 === {api-request-title}
 
@@ -36,7 +42,7 @@ default space is used.
 [[delete-rule-api-response-codes]]
 === {api-response-codes-title}
 
-`200`::
+`204`::
 Indicates a successful call.
 
 === {api-examples-title}

diff --git a/docs/api/alerting/get_rules.asciidoc b/docs/api/alerting/get_rules.asciidoc
@@ -6,6 +6,12 @@
 
 Retrieve a rule by ID.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/x-pack/plugins/alerting/docs/openapi[open API specification]. For a preview, check out <<rule-apis>>.
+====
+
 [[get-rule-api-request]]
 === {api-request-title}
 
@@ -55,33 +61,63 @@ The API returns the following:
 [source,sh]
 --------------------------------------------------
 {
-  "id": "0a037d60-6b62-11eb-9e0d-85d233e3ee35",
-  "notify_when": "onActionGroupChange",
-  "params": {
-    "aggType": "avg",
+  "id":"31697a40-7b36-11ed-aa79-f742c05329b2",
+  "consumer":"alerts",
+  "tags":["cpu"],
+  "name":"my alert",
+  "enabled":true,
+  "throttle":null,
+  "schedule":{
+    "interval":"1m"
+  },
+  "params":{
+    "aggType":"avg",
+    "termSize":6,
+    "thresholdComparator":">",
+    "timeWindowSize":5,
+    "timeWindowUnit":"m",
+    "groupBy":"top",
+    "threshold":[1000],
+    "index":["test-index"],
+    "timeField":"@timestamp",
+    "aggField":"sheet.version",
+    "termField":"name.keyword"
+    },
+  "rule_type_id":".index-threshold",
+  "created_by":"elastic",
+  "updated_by":"elastic",
+  "created_at":"2022-12-13T22:33:41.163Z",
+  "updated_at":"2022-12-13T22:33:41.163Z",
+  "api_key_owner":"elastic",
+  "notify_when":"onActionGroupChange",
+  "muted_alert_ids":[],
+  "mute_all":false,
+  "scheduled_task_id":"31697a40-7b36-11ed-aa79-f742c05329b2",
+  "execution_status":{
+    "status":"ok",
+    "last_execution_date":"2022-12-13T22:33:44.388Z",
+    "last_duration":83
   },
-  "consumer": "alerts",
-  "rule_type_id": "test.rule.type",
-  "schedule": {
-    "interval": "1m"
+  "actions":[{
+    "group":"threshold met",
+    "id":"1007a0c0-7a6e-11ed-89d5-abec321c0def",
+    "params":{
+      "level":"info",
+      "message":"alert {{alertName}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
+    },
+    "connector_type_id":".server-log"
+  }],
+  "last_run":{
+    "alerts_count":{
+      "new":0,
+      "ignored":0,
+      "recovered":0,
+      "active":0
+    },
+    "outcome_msg":null,
+    "warning":null,
+    "outcome":"succeeded"
   },
-  "actions": [],
-  "tags": [],
-  "name": "test rule",
-  "enabled": true,
-  "throttle": null,
-  "api_key_owner": "elastic",
-  "created_by": "elastic",
-  "updated_by": "elastic",
-  "mute_all": false,
-  "muted_alert_ids": [],
-  "updated_at": "2021-02-10T05:37:19.086Z",
-  "created_at": "2021-02-10T05:37:19.086Z",
-  "scheduled_task_id": "0b092d90-6b62-11eb-9e0d-85d233e3ee35",
-  "execution_status": {
-    "last_execution_date": "2021-02-10T17:55:14.262Z",
-    "status": "ok",
-    "last_duration": 359
-  }
+  "next_run":"2022-12-13T22:34:44.314Z"
 }
 --------------------------------------------------
diff --git a/docs/api/alerting/update_rule.asciidoc b/docs/api/alerting/update_rule.asciidoc
@@ -6,6 +6,12 @@
 
 Update the attributes for an existing rule.
 
+[NOTE]
+====
+For the most up-to-date API details, refer to the
+{kib-repo}/tree/{branch}/x-pack/plugins/alerting/docs/openapi[open API specification]. For a preview, check out <<rule-apis>>.
+====
+
 [[update-rule-api-request]]
 === {api-request-title}
 
@@ -132,7 +138,6 @@ PUT api/alerting/rule/ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74
     "timeWindowUnit":"m",
     "thresholdComparator":">",
     "threshold":[1000],
-    "aggType":"avg",
     "aggField":"sheet.version",
     "termField":"name.keyword",
     "termSize":6
@@ -180,16 +185,28 @@ The API returns the following:
   "updated_by": "elastic",
   "rule_type_id": ".index-threshold",
   "scheduled_task_id": "4c5eda00-e74f-11ec-b72f-5b18752ff9ea",
-  "created_at": "2022-06-08T17:20:31.632Z",
-  "updated_at": "2022-06-09T23:36:36.090Z",
+  "created_at": "2022-12-12T22:43:20.578Z",
+  "updated_at": "2022-12-12T22:44:21.783Z",
   "notify_when": "onActionGroupChange",
   "mute_all": false,
   "muted_alert_ids": [],
   "execution_status": {
     "status": "ok",
-    "last_execution_date": "2022-06-09T23:36:17.332Z",
-    "last_duration": 577
+    "last_execution_date": "2022-12-12T22:43:21.723Z",
+    "last_duration": 125
+  },
+  "actions":[],
+  "last_run":{
+    "alerts_count": {
+      "new": 0,
+      "ignored": 0,
+      "recovered": 0,
+      "active": 0
+    },
+    "outcome_msg" :null,
+    "warning": null,
+    "outcome": "succeeded"
   },
-  "actions":[]
+  "next_run": "2022-12-12T22:44:21.653Z"
 }
 --------------------------------------------------