From 470590b5e9ca03ae236c9d3db25b01d6f9c554e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 7 Oct 2024 09:11:30 +0200 Subject: [PATCH] Adds index API requests and responses - part 1 (#2979) Co-authored-by: lcawl --- .../elasticsearch-openapi-overlays.yaml | 39 +++++++- .../elasticsearch-shared-overlays.yaml | 91 ++++++++++++++++++- .../IndicesAddBlockResponseExample1.yaml | 7 ++ .../indicesAnalyzeRequestExample1.yaml | 5 + .../clone/indicesCloneRequestExample1.yaml | 8 ++ .../close/indicesCloseResponseExample1.yaml | 7 ++ .../create/indicesCreateRequestExample1.yaml | 7 ++ .../create/indicesCreateRequestExample2.yaml | 7 ++ ...ndicesDataStreamStatsResponseExample1.yaml | 13 +++ ...esDeleteDataLifecycleResponseExample1.yaml | 5 + ...sExplainDataLifecycleResponseExample1.yaml | 11 +++ ...dicesGetDataLifecycleResponseExample1.yaml | 10 ++ .../indicesGetDataStreamResponseExample1.yaml | 32 +++++++ .../open/indicesOpenResponseExample1.yaml | 5 + ...ndicesPutDataLifecycleRequestExample1.yaml | 5 + ...ndicesPutDataLifecycleRequestExample2.yaml | 8 ++ ...dicesPutDataLifecycleResponseExample1.yaml | 5 + 17 files changed, 261 insertions(+), 4 deletions(-) create mode 100644 specification/indices/add_block/IndicesAddBlockResponseExample1.yaml create mode 100644 specification/indices/analyze/indicesAnalyzeRequestExample1.yaml create mode 100644 specification/indices/clone/indicesCloneRequestExample1.yaml create mode 100644 specification/indices/close/indicesCloseResponseExample1.yaml create mode 100644 specification/indices/create/indicesCreateRequestExample1.yaml create mode 100644 specification/indices/create/indicesCreateRequestExample2.yaml create mode 100644 specification/indices/data_streams_stats/indicesDataStreamStatsResponseExample1.yaml create mode 100644 specification/indices/delete_data_lifecycle/IndicesDeleteDataLifecycleResponseExample1.yaml create mode 100644 specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleResponseExample1.yaml create mode 100644 specification/indices/get_data_lifecycle/IndicesGetDataLifecycleResponseExample1.yaml create mode 100644 specification/indices/get_data_stream/indicesGetDataStreamResponseExample1.yaml create mode 100644 specification/indices/open/indicesOpenResponseExample1.yaml create mode 100644 specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample1.yaml create mode 100644 specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample2.yaml create mode 100644 specification/indices/put_data_lifecycle/IndicesPutDataLifecycleResponseExample1.yaml diff --git a/docs/overlays/elasticsearch-openapi-overlays.yaml b/docs/overlays/elasticsearch-openapi-overlays.yaml index c83d58900c..57a9442d3b 100644 --- a/docs/overlays/elasticsearch-openapi-overlays.yaml +++ b/docs/overlays/elasticsearch-openapi-overlays.yaml @@ -226,4 +226,41 @@ actions: application/json: examples: removePolicyResponseExample1: - $ref: "../../specification/ilm/remove_policy/RemovePolicyResponseExample1.json" \ No newline at end of file + $ref: "../../specification/ilm/remove_policy/RemovePolicyResponseExample1.json" + - target: "$.components['requestBodies']['indices.clone']" + description: "Add examples for clone index request" + update: + content: + application/json: + examples: + indicesCloneRequestExample1: + $ref: "../../specification/indices/clone/indicesCloneRequestExample1.yaml" + - target: "$.paths['/{index}/_close']['post']" + description: "Add examples for close index response" + update: + responses: + 200: + content: + application/json: + examples: + indicesCloseResponseExample1: + $ref: "../../specification/indices/close/indicesCloseResponseExample1.yaml" + - target: "$.components['responses']['indices.data_streams_stats#200']" + description: "Add example for data stream stats response" + update: + content: + application/json: + examples: + indicesDataStreamStatsResponseExample1: + $ref: "../../specification/indices/data_streams_stats/indicesDataStreamStatsResponseExample1.yaml" + - target: "$.paths['/{index}/_open']['post']" + description: "Add examples for open index response" + update: + responses: + 200: + content: + application/json: + examples: + indicesOpenResponseExample1: + $ref: "../../specification/indices/open/indicesOpenResponseExample1.yaml" + diff --git a/docs/overlays/elasticsearch-shared-overlays.yaml b/docs/overlays/elasticsearch-shared-overlays.yaml index aedbd12ae0..6485fcd3d1 100644 --- a/docs/overlays/elasticsearch-shared-overlays.yaml +++ b/docs/overlays/elasticsearch-shared-overlays.yaml @@ -302,7 +302,7 @@ actions: content: application/json: examples: - asyncSearchSubmitResponseExample1: + asyncSearchSubmitRequestExample1: $ref: "../../specification/async_search/submit/AsyncSearchSubmitRequestExample1.json" - target: "$.components['responses']['async_search.submit#200']" description: "Add example for asynch search submit response" @@ -338,7 +338,7 @@ actions: examples: previewTransformRequestExample1: $ref: "../../specification/transform/preview_transform/PreviewTransformRequestExample1.json" - - target: "$.components['reponses']['transform.preview_transform#200']" + - target: "$.components['responses']['transform.preview_transform#200']" description: "Add examples for preview transform operation" update: content: @@ -406,4 +406,89 @@ actions: application/json: examples: graphExploreRequestExample1: - $ref: "../../specification/graph/explore/graphExploreRequestExample1.json" \ No newline at end of file + $ref: "../../specification/graph/explore/graphExploreRequestExample1.json" + - target: "$.paths['/{index}/_block/{block}']['put']" + description: "Add examples for add index block operation" + update: + responses: + 200: + content: + application/json: + examples: + indicesAddBlockResponseExample1: + $ref: "../../specification/indices/add_block/IndicesAddBlockResponseExample1.yaml" + - target: "$.components['requestBodies']['indices.analyze']" + description: "Add example for analyze API request" + update: + content: + application/json: + examples: + indicesAnalyzeRequestExample1: + $ref: "../../specification/indices/analyze/indicesAnalyzeRequestExample1.yaml" + - target: "$.paths['/{index}']['put']" + description: "Add examples for create index request" + update: + requestBody: + content: + application/json: + examples: + indicesCreateRequestExample1: + $ref: "../../specification/indices/create/indicesCreateRequestExample1.yaml" + indicesCreateRequestExample2: + $ref: "../../specification/indices/create/indicesCreateRequestExample2.yaml" + - target: "$.paths['/_data_stream/{name}/_lifecycle']['delete']" + description: "Add example for delete data stream lifecycle response" + update: + responses: + 200: + content: + application/json: + examples: + indicesDeleteDataLifecycleResponseExample1: + $ref: "../../specification/indices/delete_data_lifecycle/IndicesDeleteDataLifecycleResponseExample1.yaml" + - target: "$.paths['/_data_stream/{name}/_lifecycle']['get']" + description: "Add example for get data stream lifecycle response" + update: + responses: + 200: + content: + application/json: + examples: + indicesGetDataLifecycleResponseExample1: + $ref: "../../specification/indices/get_data_lifecycle/IndicesGetDataLifecycleResponseExample1.yaml" + - target: "$.components['responses']['indices.get_data_stream#200']" + description: "Add example for get data stream response" + update: + content: + application/json: + examples: + indicesGetDataStreamResponseExample: + $ref: "../../specification/indices/get_data_stream/indicesGetDataStreamResponseExample1.yaml" + - target: "$.paths['/_data_stream/{name}/_lifecycle']['put']" + description: "Add examples update data stream lifecycle request and response" + update: + requestBody: + content: + application/json: + examples: + indicesPutDataLifecycleRequestExample1: + $ref: "../../specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample1.yaml" + indicesPutLifecycleRequestExample2: + $ref: "../../specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample2.yaml" + responses: + 200: + content: + application/json: + examples: + indicesPutDataLifecycleResponseExample1: + $ref: "../../specification/indices/put_data_lifecycle/IndicesPutDataLifecycleResponseExample1.yaml" + - target: "$.paths['/{index}/_lifecycle/explain']['get']" + description: "Add example for explain data stream lifecycle response" + update: + responses: + 200: + content: + application/json: + examples: + indicesExplainDataLifecycleResponseExample: + $ref: "../../specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleResponseExample1.yaml" \ No newline at end of file diff --git a/specification/indices/add_block/IndicesAddBlockResponseExample1.yaml b/specification/indices/add_block/IndicesAddBlockResponseExample1.yaml new file mode 100644 index 0000000000..fec4fafd17 --- /dev/null +++ b/specification/indices/add_block/IndicesAddBlockResponseExample1.yaml @@ -0,0 +1,7 @@ +# summary: '' +description: 'A successful response for adding an index block to an index.' +# type: response +# response_code: 200 +value: + "{\n \"acknowledged\" : true,\n \"shards_acknowledged\" : true,\n \"indices\"\ + \ : [ {\n \"name\" : \"my-index-000001\",\n \"blocked\" : true\n } ]\n}" diff --git a/specification/indices/analyze/indicesAnalyzeRequestExample1.yaml b/specification/indices/analyze/indicesAnalyzeRequestExample1.yaml new file mode 100644 index 0000000000..4b6f322b7a --- /dev/null +++ b/specification/indices/analyze/indicesAnalyzeRequestExample1.yaml @@ -0,0 +1,5 @@ +summary: Perform analysis on a text string and returns the resulting tokens. +method_request: GET /_analyze +# description: '' +# type: request +value: "{\n \"analyzer\" : \"standard\",\n \"text\" : \"Quick Brown Foxes!\"\n}" diff --git a/specification/indices/clone/indicesCloneRequestExample1.yaml b/specification/indices/clone/indicesCloneRequestExample1.yaml new file mode 100644 index 0000000000..6578cc0db6 --- /dev/null +++ b/specification/indices/clone/indicesCloneRequestExample1.yaml @@ -0,0 +1,8 @@ +summary: Clone an existing index. +# method_request: POST /my_source_index/_clone/my_target_index +description: > + Clone `my_source_index` into a new index called `my_target_index` with `POST /my_source_index/_clone/my_target_index`. The API accepts `settings` and `aliases` parameters for the target index. +# type: request +value: + "{\n \"settings\": {\n \"index.number_of_shards\": 5\n },\n \"aliases\"\ + : {\n \"my_search_indices\": {}\n }\n}" diff --git a/specification/indices/close/indicesCloseResponseExample1.yaml b/specification/indices/close/indicesCloseResponseExample1.yaml new file mode 100644 index 0000000000..bd3bcd0dc7 --- /dev/null +++ b/specification/indices/close/indicesCloseResponseExample1.yaml @@ -0,0 +1,7 @@ +# summary: '' +description: A successful response for closing an index. +# type: response +# response_code: 200 +value: + "{\n \"acknowledged\": true,\n \"shards_acknowledged\": true,\n \"indices\"\ + : {\n \"my-index-000001\": {\n \"closed\": true\n }\n }\n}" diff --git a/specification/indices/create/indicesCreateRequestExample1.yaml b/specification/indices/create/indicesCreateRequestExample1.yaml new file mode 100644 index 0000000000..21a40348d1 --- /dev/null +++ b/specification/indices/create/indicesCreateRequestExample1.yaml @@ -0,0 +1,7 @@ +summary: Creates an index. +# method_request: PUT /my-index-000001 +description: This request specifies the `number_of_shards` and `number_of_replicas`. +# type: request +value: + "{\n \"settings\": {\n \"number_of_shards\": 3,\n \"number_of_replicas\"\ + : 2\n }\n}" diff --git a/specification/indices/create/indicesCreateRequestExample2.yaml b/specification/indices/create/indicesCreateRequestExample2.yaml new file mode 100644 index 0000000000..a64d16b63f --- /dev/null +++ b/specification/indices/create/indicesCreateRequestExample2.yaml @@ -0,0 +1,7 @@ +summary: Creates an index with mapping. +# method_request: PUT /test +description: You can provide mapping definitions in the create index API requests. +# type: request +value: + "{\n \"settings\": {\n \"number_of_shards\": 1\n },\n \"mappings\": {\n\ + \ \"properties\": {\n \"field1\": { \"type\": \"text\" }\n }\n }\n}" diff --git a/specification/indices/data_streams_stats/indicesDataStreamStatsResponseExample1.yaml b/specification/indices/data_streams_stats/indicesDataStreamStatsResponseExample1.yaml new file mode 100644 index 0000000000..9f2a04a082 --- /dev/null +++ b/specification/indices/data_streams_stats/indicesDataStreamStatsResponseExample1.yaml @@ -0,0 +1,13 @@ +# summary: '' +description: A successful response for retrieving statistics for a data stream. +# type: response +# response_code: 200 +value: + "{\n \"_shards\": {\n \"total\": 10,\n \"successful\": 5,\n \"failed\"\ + : 0\n },\n \"data_stream_count\": 2,\n \"backing_indices\": 5,\n \"total_store_size\"\ + : \"7kb\",\n \"total_store_size_bytes\": 7268,\n \"data_streams\": [\n {\n\ + \ \"data_stream\": \"my-data-stream\",\n \"backing_indices\": 3,\n \ + \ \"store_size\": \"3.7kb\",\n \"store_size_bytes\": 3772,\n \"maximum_timestamp\"\ + : 1607512028000\n },\n {\n \"data_stream\": \"my-data-stream-two\",\n\ + \ \"backing_indices\": 2,\n \"store_size\": \"3.4kb\",\n \"store_size_bytes\"\ + : 3496,\n \"maximum_timestamp\": 1607425567000\n }\n ]\n}" diff --git a/specification/indices/delete_data_lifecycle/IndicesDeleteDataLifecycleResponseExample1.yaml b/specification/indices/delete_data_lifecycle/IndicesDeleteDataLifecycleResponseExample1.yaml new file mode 100644 index 0000000000..2a7ab3248b --- /dev/null +++ b/specification/indices/delete_data_lifecycle/IndicesDeleteDataLifecycleResponseExample1.yaml @@ -0,0 +1,5 @@ +# summary: '' +description: A successful response for deleting a data stream lifecycle. +# type: response +# response_code: 200 +value: "{\n \"acknowledged\": true\n}" diff --git a/specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleResponseExample1.yaml b/specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleResponseExample1.yaml new file mode 100644 index 0000000000..33e6bc7cdf --- /dev/null +++ b/specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleResponseExample1.yaml @@ -0,0 +1,11 @@ +# summary: '' +description: A successful response for retrieving data stream lifecycle status for a data stream backing index. +# type: response +# response_code: 200 +value: + "{\n \"indices\": {\n \".ds-metrics-2023.03.22-000001\": {\n \"index\"\ + \ : \".ds-metrics-2023.03.22-000001\",\n \"managed_by_lifecycle\" : true,\n\ + \ \"index_creation_date_millis\" : 1679475563571,\n \"time_since_index_creation\"\ + \ : \"843ms\",\n \"rollover_date_millis\" : 1679475564293,\n \"time_since_rollover\"\ + \ : \"121ms\",\n \"lifecycle\" : { },\n \"generation_time\" : \"121ms\"\ + \n }\n}" diff --git a/specification/indices/get_data_lifecycle/IndicesGetDataLifecycleResponseExample1.yaml b/specification/indices/get_data_lifecycle/IndicesGetDataLifecycleResponseExample1.yaml new file mode 100644 index 0000000000..b50b49f023 --- /dev/null +++ b/specification/indices/get_data_lifecycle/IndicesGetDataLifecycleResponseExample1.yaml @@ -0,0 +1,10 @@ +# summary: +description: A successful response of getting the lifecycle of a set of data streams. +# type: response +# response_code: 200 +value: + "{\n \"data_streams\": [\n {\n \"name\": \"my-data-stream-1\",\n \ + \ \"lifecycle\": {\n \"enabled\": true,\n \"data_retention\":\ + \ \"7d\"\n }\n },\n {\n \"name\": \"my-data-stream-2\",\n \"\ + lifecycle\": {\n \"enabled\": true,\n \"data_retention\": \"7d\"\n\ + \ }\n }\n ]\n}" diff --git a/specification/indices/get_data_stream/indicesGetDataStreamResponseExample1.yaml b/specification/indices/get_data_stream/indicesGetDataStreamResponseExample1.yaml new file mode 100644 index 0000000000..0b992d9afb --- /dev/null +++ b/specification/indices/get_data_stream/indicesGetDataStreamResponseExample1.yaml @@ -0,0 +1,32 @@ +# summary: +description: A successful response for retrieving information about a data stream. +# type: response +# response_code: 200 +value: + "{\n \"data_streams\": [\n {\n \"name\": \"my-data-stream\",\n \ + \ \"timestamp_field\": {\n \"name\": \"@timestamp\"\n },\n \"\ + indices\": [\n {\n \"index_name\": \".ds-my-data-stream-2099.03.07-000001\"\ + ,\n \"index_uuid\": \"xCEhwsp8Tey0-FLNFYVwSg\",\n \"prefer_ilm\"\ + : true,\n \"ilm_policy\": \"my-lifecycle-policy\",\n \"managed_by\"\ + : \"Index Lifecycle Management\"\n },\n {\n \"index_name\"\ + : \".ds-my-data-stream-2099.03.08-000002\",\n \"index_uuid\": \"PA_JquKGSiKcAKBA8DJ5gw\"\ + ,\n \"prefer_ilm\": true,\n \"ilm_policy\": \"my-lifecycle-policy\"\ + ,\n \"managed_by\": \"Index Lifecycle Management\"\n }\n ],\n\ + \ \"generation\": 2,\n \"_meta\": {\n \"my-meta-field\": \"foo\"\ + \n },\n \"status\": \"GREEN\",\n \"next_generation_managed_by\":\ + \ \"Index Lifecycle Management\",\n \"prefer_ilm\": true,\n \"template\"\ + : \"my-index-template\",\n \"ilm_policy\": \"my-lifecycle-policy\",\n \ + \ \"hidden\": false,\n \"system\": false,\n \"allow_custom_routing\":\ + \ false,\n \"replicated\": false,\n \"rollover_on_write\": false\n \ + \ },\n {\n \"name\": \"my-data-stream-two\",\n \"timestamp_field\"\ + : {\n \"name\": \"@timestamp\"\n },\n \"indices\": [\n {\n\ + \ \"index_name\": \".ds-my-data-stream-two-2099.03.08-000001\",\n \ + \ \"index_uuid\": \"3liBu2SYS5axasRt6fUIpA\",\n \"prefer_ilm\": true,\n\ + \ \"ilm_policy\": \"my-lifecycle-policy\",\n \"managed_by\": \"\ + Index Lifecycle Management\"\n }\n ],\n \"generation\": 1,\n \ + \ \"_meta\": {\n \"my-meta-field\": \"foo\"\n },\n \"status\"\ + : \"YELLOW\",\n \"next_generation_managed_by\": \"Index Lifecycle Management\"\ + ,\n \"prefer_ilm\": true,\n \"template\": \"my-index-template\",\n \ + \ \"ilm_policy\": \"my-lifecycle-policy\",\n \"hidden\": false,\n \"\ + system\": false,\n \"allow_custom_routing\": false,\n \"replicated\":\ + \ false,\n \"rollover_on_write\": false\n }\n ]\n}" diff --git a/specification/indices/open/indicesOpenResponseExample1.yaml b/specification/indices/open/indicesOpenResponseExample1.yaml new file mode 100644 index 0000000000..10eb656f86 --- /dev/null +++ b/specification/indices/open/indicesOpenResponseExample1.yaml @@ -0,0 +1,5 @@ +# summary: +description: A successful response for opening an index. +# type: response +# response_code: 200 +value: "{\n \"acknowledged\" : true,\n \"shards_acknowledged\" : true\n}" diff --git a/specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample1.yaml b/specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample1.yaml new file mode 100644 index 0000000000..86309ad5a5 --- /dev/null +++ b/specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample1.yaml @@ -0,0 +1,5 @@ +summary: Set the data stream lifecycle retention +# method_request: PUT _data_stream/my-data-stream/_lifecycle +# description: Sets the lifecycle of a data stream. +# type: request +value: "{\n \"data_retention\": \"7d\"\n}" diff --git a/specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample2.yaml b/specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample2.yaml new file mode 100644 index 0000000000..1b318274b1 --- /dev/null +++ b/specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample2.yaml @@ -0,0 +1,8 @@ +summary: Set the data stream lifecycle downsampling +# method_request: PUT _data_stream/my-weather-sensor-data-stream/_lifecycle +description: This example configures two downsampling rounds. +# type: request +value: + "{\n \"downsampling\": [\n {\n \"after\": \"1d\",\n \"\ + fixed_interval\": \"10m\"\n },\n {\n \"after\": \"7d\",\n \ + \ \"fixed_interval\": \"1d\"\n }\n ]\n}" diff --git a/specification/indices/put_data_lifecycle/IndicesPutDataLifecycleResponseExample1.yaml b/specification/indices/put_data_lifecycle/IndicesPutDataLifecycleResponseExample1.yaml new file mode 100644 index 0000000000..02815ba8ec --- /dev/null +++ b/specification/indices/put_data_lifecycle/IndicesPutDataLifecycleResponseExample1.yaml @@ -0,0 +1,5 @@ +# summary: +description: A successful response for configuring a data stream lifecycle. +# type: response +# response_code: 200 +value: "{\n \"acknowledged\": true\n}"