Adds EQL, ESQL, features API example requests and responses (#2879)

Co-authored-by: lcawl <[email protected]>
elastic · Sep 13, 2024 · a37d021 · a37d021
1 parent b26b9a1
commit a37d021
Show file tree

Hide file tree

Showing 10 changed files with 112 additions and 4 deletions.
diff --git a/docs/overlays/elasticsearch-openapi-overlays.yaml b/docs/overlays/elasticsearch-openapi-overlays.yaml
@@ -1,4 +1,4 @@
-# overlays.yaml
+# Overlays that are specific to the Elasticsearch OpenAPI document
 overlay: 1.0.0
 info:
   title: Overlays for the Elasticsearch OpenAPI document
@@ -19,3 +19,25 @@ actions:
       x-feedbackLink:
         label: Feedback
         url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
+# Examples that apply only to the Elasticsearch OpenAPI document
+  - target: "$.paths['/_features']['get']"
+    description: "Add examples for get features operation"
+    update:
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                getFeaturesResponseExample1:
+                  $ref: "../../specification/features/get_features/FeaturesApiResponseExample1.json"
+  - target: "$.paths['/_features/_reset']['post']"
+    description: "Add examples for reset features operation"
+    update:
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                resetFeaturesResponseExample1:
+                  $ref: "../../specification/features/reset_features/ResetFeaturesResponseExample1.json"
+
diff --git a/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml b/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml
@@ -1,4 +1,4 @@
-# overlays.yaml
+# Overlays that are specific to the Elasticsearch Serverless OpenAPI document
 overlay: 1.0.0
 info:
   title: Overlays for the Elasticsearch Serverless OpenAPI document

diff --git a/docs/overlays/elasticsearch-shared-example-overlays.yaml b/docs/overlays/elasticsearch-shared-example-overlays.yaml
@@ -1,4 +1,4 @@
-# overlays.yaml
+# Overlays that are applicable to both Elasticsearch and Elasticsearch Serverless OpenAPI documents
 overlay: 1.0.0
 info:
   title: Overlays for examples that apply to both Elasticsearcb and Elasticsearch Serverless OpenAPI documents
@@ -69,4 +69,41 @@ actions:
             application/json:
               examples:
                 updateTransformResponseExample1:
-                  $ref: "../../specification/transform/update_transform/UpdateTransformResponseExample1.json"
+                  $ref: "../../specification/transform/update_transform/UpdateTransformResponseExample1.json"
+  - target: "$.paths['/_eql/search/status/{id}']['get']"
+    description: "Add examples for get async EQL status operation"
+    update: 
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                eqlGetStatusResponseExample1:
+                  $ref: "../../specification/eql/get_status/EqlGetStatusResponseExample1.json"
+  - target: "$.components['requestBodies']['eql.search']"
+    description: "Add examples for EQL search operation"
+    update: 
+      content: 
+        application/json: 
+          examples: 
+            eqlSearchRequestExample1: 
+              $ref: "../../specification/eql/search/EqlSearchRequestExample1.json"
+            eqlSearchRequestExample2: 
+              $ref: "../../specification/eql/search/EqlSearchRequestExample2.json"
+  - target: "$.components['reponses']['eql.search#200']"
+    description: "Add examples for EQL search operation"
+    update: 
+      content:
+        application/json:
+          examples:
+            eqlSearchResponseExample2:
+              $ref: "../../specification/eql/search/EqlSearchResponseExample2.json"
+  - target: "$.paths['/_query']['post']"
+    description: "Add examples for ES|QL query operation"
+    update: 
+      requestBody: 
+        content: 
+          application/json: 
+            examples: 
+              esqlQueryRequestExample1: 
+                $ref: "../../specification/esql/query/EsqlQueryApiRequestExample1.json"
diff --git a/specification/eql/get_status/EqlGetStatusResponseExample1.json b/specification/eql/get_status/EqlGetStatusResponseExample1.json
@@ -0,0 +1,7 @@
+{
+  "summary": "A successful response for getting status information for an async EQL search.",
+  "description": "",
+  "type": "response",
+  "response_code": 200,
+  "value": "{\n  \"id\" : \"FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=\",\n  \"is_running\" : true,\n  \"is_partial\" : true,\n  \"start_time_in_millis\" : 1611690235000,\n  \"expiration_time_in_millis\" : 1611690295000\n\n}"
+}
diff --git a/specification/eql/search/EqlSearchRequestExample1.json b/specification/eql/search/EqlSearchRequestExample1.json
@@ -0,0 +1,7 @@
+{
+  "summary": "Returns search results for an EQL query.",
+  "method_request": "GET /my-data-stream/_eql/search",
+  "description": "",
+  "type": "request",
+  "value": "{\n  \"query\": \"\"\"\n    process where process.name == \"regsvr32.exe\"\n  \"\"\"\n}"
+}
diff --git a/specification/eql/search/EqlSearchRequestExample2.json b/specification/eql/search/EqlSearchRequestExample2.json
@@ -0,0 +1,7 @@
+{
+  "summary": "Returns search results for an EQL query",
+  "method_request": "GET /my-data-stream/_eql/search",
+  "description": "",
+  "type": "request",
+  "value": "{\n  \"query\": \"\"\"\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  \"\"\"\n}"
+}
diff --git a/specification/eql/search/EqlSearchResponseExample2.json b/specification/eql/search/EqlSearchResponseExample2.json
@@ -0,0 +1,7 @@
+{
+  "summary": "A successful response for performing search with an EQL query.",
+  "description": "",
+  "type": "response",
+  "response_code": 200,
+  "value": "{\n  \"is_partial\": false,\n  \"is_running\": false,\n  \"took\": 6,\n  \"timed_out\": false,\n  \"hits\": {\n    \"total\": {\n      \"value\": 1,\n      \"relation\": \"eq\"\n    },\n    \"sequences\": [\n      {\n        \"join_keys\": [\n          2012\n        ],\n        \"events\": [\n          {\n            \"_index\": \".ds-my-data-stream-2099.12.07-000001\",\n            \"_id\": \"AtOJ4UjUBAAx3XR5kcCM\",\n            \"_source\": {\n              \"@timestamp\": \"2099-12-06T11:04:07.000Z\",\n              \"event\": {\n                \"category\": \"file\",\n                \"id\": \"dGCHwoeS\",\n                \"sequence\": 2\n              },\n              \"file\": {\n                \"accessed\": \"2099-12-07T11:07:08.000Z\",\n                \"name\": \"cmd.exe\",\n                \"path\": \"C:\\\\Windows\\\\System32\\\\cmd.exe\",\n                \"type\": \"file\",\n                \"size\": 16384\n              },\n              \"process\": {\n                \"pid\": 2012,\n                \"name\": \"cmd.exe\",\n                \"executable\": \"C:\\\\Windows\\\\System32\\\\cmd.exe\"\n              }\n            }\n          },\n          {\n            \"_index\": \".ds-my-data-stream-2099.12.07-000001\",\n            \"_id\": \"OQmfCaduce8zoHT93o4H\",\n            \"_source\": {\n              \"@timestamp\": \"2099-12-07T11:07:09.000Z\",\n              \"event\": {\n                \"category\": \"process\",\n                \"id\": \"aR3NWVOs\",\n                \"sequence\": 4\n              },\n              \"process\": {\n                \"pid\": 2012,\n                \"name\": \"regsvr32.exe\",\n                \"command_line\": \"regsvr32.exe  /s /u /i:https://...RegSvr32.sct scrobj.dll\",\n                \"executable\": \"C:\\\\Windows\\\\System32\\\\regsvr32.exe\"\n              }\n            }\n          }\n        ]\n      }\n    ]\n  }\n}"
+}
diff --git a/specification/esql/query/EsqlQueryApiRequestExample1.json b/specification/esql/query/EsqlQueryApiRequestExample1.json
@@ -0,0 +1,7 @@
+{
+  "summary": "Returns results for an ES|QL query.",
+  "method_request": "POST /_query",
+  "description": "",
+  "type": "request",
+  "value": "{\n  \"query\": \"\"\"\n    FROM library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  \"\"\"\n}"
+}
diff --git a/specification/features/get_features/FeaturesApiResponseExample1.json b/specification/features/get_features/FeaturesApiResponseExample1.json
@@ -0,0 +1,7 @@
+{
+  "summary": "A successful response for retrieving a list of feature states that can be included when taking a snapshot.",
+  "description": "",
+  "type": "response",
+  "response_code": 200,
+  "value": "{\n    \"features\": [\n        {\n            \"name\": \"tasks\",\n            \"description\": \"Manages task results\"\n        },\n        {\n            \"name\": \"kibana\",\n            \"description\": \"Manages Kibana configuration and reports\"\n        }\n    ]\n}"
+}
diff --git a/specification/features/reset_features/ResetFeaturesResponseExample1.json b/specification/features/reset_features/ResetFeaturesResponseExample1.json
@@ -0,0 +1,7 @@
+{
+  "summary": "A successful response for clearing state information stored in system indices by Elasticsearch features.",
+  "description": "",
+  "type": "response",
+  "response_code": 200,
+  "value": "{\n  \"features\" : [\n    {\n      \"feature_name\" : \"security\",\n      \"status\" : \"SUCCESS\"\n    },\n    {\n      \"feature_name\" : \"tasks\",\n      \"status\" : \"SUCCESS\"\n    }\n  ]\n}"
+}