diff --git a/docs/add-new-api.md b/docs/add-new-api.md index a124f4e47d..f41882785a 100644 --- a/docs/add-new-api.md +++ b/docs/add-new-api.md @@ -38,8 +38,7 @@ interface Request {} class Response {} ``` -Try to use less files as possible, for example there is no need to create a custom file for an enum, -you can define it in the same file where it's used, unless is a commonly used type. +Try to use the least number of files possible, for example there is no need to create a custom file for an enum as you can define it in the same file where it's used, unless is a commonly used type. ### Add the endpoint request definition diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 33b64d6604..52e51b6e60 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -900,6 +900,9 @@ stop-dfanalytics,https://www.elastic.co/docs/api/doc/elasticsearch/operation/ope stop-trained-model-deployment,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-stop-trained-model-deployment,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/stop-trained-model-deployment.html, stop-transform,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-transform-stop-transform,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/stop-transform.html, stored-fields,https://www.elastic.co/docs/reference/elasticsearch/rest-apis/retrieve-selected-fields#stored-fields,, +streams-status,https://www.elastic.co/docs/reference/elasticsearch/rest-apis,, +streams-logs-enable,https://www.elastic.co/docs/reference/elasticsearch/rest-apis,, +streams-logs-disable,https://www.elastic.co/docs/reference/elasticsearch/rest-apis,, synonym-api-examples,https://www.elastic.co/docs/solutions/search/full-text/create-update-synonyms-api-example,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonyms-set.html, synonym-rule-create,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-synonyms-put-synonym-rule,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonym-rule.html, synonym-rule-delete,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-synonyms-delete-synonym-rule,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/delete-synonym-rule.html, diff --git a/specification/streams/logs_disable/StreamsLogsDisableRequest.ts b/specification/streams/logs_disable/StreamsLogsDisableRequest.ts new file mode 100644 index 0000000000..0b5e07414a --- /dev/null +++ b/specification/streams/logs_disable/StreamsLogsDisableRequest.ts @@ -0,0 +1,51 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { RequestBase } from '@_types/Base' +import { Duration } from '@_types/Time' + +/** + * Disable logs stream + * + * This disables the logs stream feature for this cluster. + * @rest_spec_name streams.logs_disable + * @availability stack since=9.1.0 stability=experimental visibility=feature_flag feature_flag=logs_stream + * @cluster_privileges manage + * @doc_id streams-logs-disable + */ +export interface Request extends RequestBase { + urls: [ + { + path: '/_streams/logs/_disable' + methods: ['POST'] + } + ] + query_parameters: { + /** + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. + */ + master_timeout?: Duration + /** + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. + */ + timeout?: Duration + } +} diff --git a/specification/streams/logs_disable/StreamsLogsDisableResponse.ts b/specification/streams/logs_disable/StreamsLogsDisableResponse.ts new file mode 100644 index 0000000000..9e7bdb91cd --- /dev/null +++ b/specification/streams/logs_disable/StreamsLogsDisableResponse.ts @@ -0,0 +1,25 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { AcknowledgedResponseBase } from '@_types/Base' + +export class Response { + /** @codegen_name result */ + body: AcknowledgedResponseBase +} diff --git a/specification/streams/logs_disable/examples/200_response/PostStreamsLogsDisableResponseExample1.yaml b/specification/streams/logs_disable/examples/200_response/PostStreamsLogsDisableResponseExample1.yaml new file mode 100644 index 0000000000..3add46c389 --- /dev/null +++ b/specification/streams/logs_disable/examples/200_response/PostStreamsLogsDisableResponseExample1.yaml @@ -0,0 +1,6 @@ +summary: Disable logs streams +description: > + A successful response from `POST _streams/logs/_disable` endpoint +# type: response +value: + acknowledged: true diff --git a/specification/streams/logs_disable/examples/request/PostStreamsDisableRequestExample1.yaml b/specification/streams/logs_disable/examples/request/PostStreamsDisableRequestExample1.yaml new file mode 100644 index 0000000000..b286db3e0e --- /dev/null +++ b/specification/streams/logs_disable/examples/request/PostStreamsDisableRequestExample1.yaml @@ -0,0 +1,3 @@ +summary: 'Disable the logs streams on this cluster' +method_request: POST _streams/logs/_disable +# type: request diff --git a/specification/streams/logs_enable/StreamsLogsEnableRequest.ts b/specification/streams/logs_enable/StreamsLogsEnableRequest.ts new file mode 100644 index 0000000000..c7b6abc74a --- /dev/null +++ b/specification/streams/logs_enable/StreamsLogsEnableRequest.ts @@ -0,0 +1,55 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { RequestBase } from '@_types/Base' +import { Duration } from '@_types/Time' + +/** + * Enable logs stream + * + * This enables the logs stream feature for this cluster. + * + * Note: To protect existing data, this feature can only be enabled on a cluster if + * it does not have existing indices or data streams matching the pattern `logs|logs.*`. + * If this is the case, a `409 - Conflict` response and error will be returned. + * @rest_spec_name streams.logs_enable + * @availability stack since=9.1.0 stability=experimental visibility=feature_flag feature_flag=logs_stream + * @cluster_privileges manage + * @doc_id streams-logs-enable + */ +export interface Request extends RequestBase { + urls: [ + { + path: '/_streams/logs/_enable' + methods: ['POST'] + } + ] + query_parameters: { + /** + * The period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. + */ + master_timeout?: Duration + /** + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. + */ + timeout?: Duration + } +} diff --git a/specification/streams/logs_enable/StreamsLogsEnableResponse.ts b/specification/streams/logs_enable/StreamsLogsEnableResponse.ts new file mode 100644 index 0000000000..9e7bdb91cd --- /dev/null +++ b/specification/streams/logs_enable/StreamsLogsEnableResponse.ts @@ -0,0 +1,25 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { AcknowledgedResponseBase } from '@_types/Base' + +export class Response { + /** @codegen_name result */ + body: AcknowledgedResponseBase +} diff --git a/specification/streams/logs_enable/examples/200_response/PostStreamsLogsEnableResponseExample1.yaml b/specification/streams/logs_enable/examples/200_response/PostStreamsLogsEnableResponseExample1.yaml new file mode 100644 index 0000000000..bf5af6721a --- /dev/null +++ b/specification/streams/logs_enable/examples/200_response/PostStreamsLogsEnableResponseExample1.yaml @@ -0,0 +1,6 @@ +summary: Enable logs streams +description: > + A successful response from `POST _streams/logs/_enable` endpoint +# type: response +value: + acknowledged: true diff --git a/specification/streams/logs_enable/examples/409_response/PostStreamsLogsEnableResponseExample2.yaml b/specification/streams/logs_enable/examples/409_response/PostStreamsLogsEnableResponseExample2.yaml new file mode 100644 index 0000000000..5f20637ff6 --- /dev/null +++ b/specification/streams/logs_enable/examples/409_response/PostStreamsLogsEnableResponseExample2.yaml @@ -0,0 +1,19 @@ +summary: Enable logs streams - Failure due to conflicting index +description: > + An error response from the `POST _streams/logs/_enable` endpoint caused by attempting to enable logs streams + when an existing index with the name `logs` already exists +# type: response +value: |- + { + "error": { + "root_cause": [ + { + "type": "status_exception", + "reason": "Cannot enable logs streams: indices named 'logs' or starting with 'logs.' already exist." + } + ], + "type": "status_exception", + "reason": "Cannot enable logs streams: indices named 'logs' or starting with 'logs.' already exist." + }, + "status": 409 + } diff --git a/specification/streams/logs_enable/examples/request/PostStreamsEnableRequestExample1.yaml b/specification/streams/logs_enable/examples/request/PostStreamsEnableRequestExample1.yaml new file mode 100644 index 0000000000..246312fc54 --- /dev/null +++ b/specification/streams/logs_enable/examples/request/PostStreamsEnableRequestExample1.yaml @@ -0,0 +1,3 @@ +summary: 'Enable the logs streams on this cluster' +method_request: POST _streams/logs/_enable +# type: request diff --git a/specification/streams/status/StreamsStatusRequest.ts b/specification/streams/status/StreamsStatusRequest.ts new file mode 100644 index 0000000000..682cb2449a --- /dev/null +++ b/specification/streams/status/StreamsStatusRequest.ts @@ -0,0 +1,46 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { RequestBase } from '@_types/Base' +import { TimeUnit } from '@_types/Time' + +/** + * Get the status of streams + * + * Gets the current status of all stream types + * @rest_spec_name streams.status + * @availability stack since=9.1.0 stability=experimental visibility=feature_flag feature_flag=logs_stream + * @cluster_privileges monitor + * @doc_id streams-status + */ +export interface Request extends RequestBase { + urls: [ + { + path: '/_streams/status' + methods: ['GET'] + } + ] + query_parameters: { + /** + * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. + * @server_default 30s + */ + master_timeout?: TimeUnit + } +} diff --git a/specification/streams/status/StreamsStatusResponse.ts b/specification/streams/status/StreamsStatusResponse.ts new file mode 100644 index 0000000000..c5eb318485 --- /dev/null +++ b/specification/streams/status/StreamsStatusResponse.ts @@ -0,0 +1,28 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +export class Response { + body: { + logs: LogsStatus + } +} + +export class LogsStatus { + enabled: boolean +} diff --git a/specification/streams/status/examples/200_response/GetStreamsStatusResponseExample1.yaml b/specification/streams/status/examples/200_response/GetStreamsStatusResponseExample1.yaml new file mode 100644 index 0000000000..be7f745dcf --- /dev/null +++ b/specification/streams/status/examples/200_response/GetStreamsStatusResponseExample1.yaml @@ -0,0 +1,9 @@ +summary: Get Streams Status + A successful response from `GET _streams/status` that outlines the current state of all wired streams in the cluster. +# type: response +value: |- + { + "logs": { + "enabled": true + } + } diff --git a/specification/streams/status/examples/request/GetStreamsStatusRequestExample1.yaml b/specification/streams/status/examples/request/GetStreamsStatusRequestExample1.yaml new file mode 100644 index 0000000000..920ce2cc90 --- /dev/null +++ b/specification/streams/status/examples/request/GetStreamsStatusRequestExample1.yaml @@ -0,0 +1,3 @@ +summary: 'Get the current status of streams' +method_request: GET _streams/status +# type: request diff --git a/specification/tsconfig.json b/specification/tsconfig.json index e920f83fce..867d8f0655 100644 --- a/specification/tsconfig.json +++ b/specification/tsconfig.json @@ -50,6 +50,7 @@ "@shutdown/*": ["shutdown/*"], "@slm/*": ["slm/*"], "@snapshot/*": ["snapshot/*"], + "@streams/*": ["streams/*"], "@sql/*": ["sql/*"], "@ssl/*": ["ssl/*"], "@synonyms/*": ["synonyms/*"],