From a37d0218e4755ffe229c1a0efccc48e8f7d2d44b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Fri, 13 Sep 2024 16:59:39 +0200 Subject: [PATCH] Adds EQL, ESQL, features API example requests and responses (#2879) Co-authored-by: lcawl --- .../elasticsearch-openapi-overlays.yaml | 24 ++++++++++- ...ticsearch-serverless-openapi-overlays.yaml | 2 +- ...elasticsearch-shared-example-overlays.yaml | 41 ++++++++++++++++++- .../EqlGetStatusResponseExample1.json | 7 ++++ .../eql/search/EqlSearchRequestExample1.json | 7 ++++ .../eql/search/EqlSearchRequestExample2.json | 7 ++++ .../eql/search/EqlSearchResponseExample2.json | 7 ++++ .../query/EsqlQueryApiRequestExample1.json | 7 ++++ .../FeaturesApiResponseExample1.json | 7 ++++ .../ResetFeaturesResponseExample1.json | 7 ++++ 10 files changed, 112 insertions(+), 4 deletions(-) create mode 100644 specification/eql/get_status/EqlGetStatusResponseExample1.json create mode 100644 specification/eql/search/EqlSearchRequestExample1.json create mode 100644 specification/eql/search/EqlSearchRequestExample2.json create mode 100644 specification/eql/search/EqlSearchResponseExample2.json create mode 100644 specification/esql/query/EsqlQueryApiRequestExample1.json create mode 100644 specification/features/get_features/FeaturesApiResponseExample1.json create mode 100644 specification/features/reset_features/ResetFeaturesResponseExample1.json diff --git a/docs/overlays/elasticsearch-openapi-overlays.yaml b/docs/overlays/elasticsearch-openapi-overlays.yaml index 6e33dbec30..f05eef369e 100644 --- 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" + \ No newline at end of file diff --git a/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml b/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml index ff8a013400..d084f0e5a1 100644 --- 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 index 033b8fb9b0..538bc5a86b 100644 --- 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" \ No newline at end of file + $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 new file mode 100644 index 0000000000..fba73dce2e --- /dev/null +++ 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 new file mode 100644 index 0000000000..c70b89e3da --- /dev/null +++ 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 new file mode 100644 index 0000000000..cdc83203bf --- /dev/null +++ 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 new file mode 100644 index 0000000000..e35c6b3b1c --- /dev/null +++ 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 new file mode 100644 index 0000000000..40668e4211 --- /dev/null +++ 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 new file mode 100644 index 0000000000..74d1988e48 --- /dev/null +++ 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 new file mode 100644 index 0000000000..cb4a805e69 --- /dev/null +++ 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}" +}