From 802ee0d8c4287d2ade407dbf4fbd0f31732468db Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 16 Jul 2025 15:06:37 -0700 Subject: [PATCH 1/2] [DOCS] Add x-topic about versioning --- ...ticsearch-serverless-openapi-overlays.yaml | 52 ++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml b/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml index 908a526697..a03295fde1 100644 --- a/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml +++ b/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml @@ -44,4 +44,54 @@ actions: description: Add document security update: security: - - apiKeyAuth: [] \ No newline at end of file + - apiKeyAuth: [] +# Add x-topics + - target: '$' + description: Add an extra page about versioning + update: + x-topics: + - title: API versioning + content: | + Elasticsearch Serverless implements API versioning to enable backwards-incompatible changes while maintaining client compatibility. An API version is a date-based identifier that represents a guaranteed backwards-compatible API surface. + + As long as the server supports an API version and the client specifies that version, existing client code will continue to work without modification. This backwards compatibility guarantee covers request/response structure and API behavior. + + ## Guarantees + + This API versioning scheme provides several key guarantees: + + * No code changes required: Your application code remains unchanged during Serverless infrastructure upgrades. + * No manual migrations: Data, indices, and resources are migrated transparently without user intervention. + * New features available everywhere: Compatible additions like new APIs and parameters work across all supported versions. + * Predictable upgrade timeline: API versions are supported for at least 18 months after newer versions are introduced. + + ## API version format + + API versions use ISO8601 date format: `YYYY-MM-DD` (for example, `2023-10-31`). + + ## Supported versions + + Elasticsearch Serverless currently supports the following API versions: + + * `2023-10-31` + + Future breaking changes will introduce new date-based versions. + Support policies for existing versions will be announced when new versions are released. + + ## How to specify API versions + + Clients specify API versions using the `Elastic-Api-Version` HTTP header: + + ``` + GET /_search HTTP/1.1 + Elastic-Api-Version: 2023-10-31 + ``` + + ### Server responses + + The server's response depends on whether the client provides a version header: + + * When a client sends the `Elastic-Api-Version` header, the server processes the request using the specified API version or returns HTTP 400 if the version is unsupported or malformed. + * When no version header is provided, the server defaults to the latest supported API version. + + The server always includes the Elastic-Api-Version header in successful responses to indicate which version was used. From 7cc77e5fe5a94ea8d8303f3023f4a08989f1a027 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 16 Jul 2025 15:14:53 -0700 Subject: [PATCH 2/2] Fix indentation --- ...ticsearch-serverless-openapi-overlays.yaml | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml b/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml index a03295fde1..60fa778612 100644 --- a/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml +++ b/docs/overlays/elasticsearch-serverless-openapi-overlays.yaml @@ -64,34 +64,34 @@ actions: * No manual migrations: Data, indices, and resources are migrated transparently without user intervention. * New features available everywhere: Compatible additions like new APIs and parameters work across all supported versions. * Predictable upgrade timeline: API versions are supported for at least 18 months after newer versions are introduced. - - ## API version format - - API versions use ISO8601 date format: `YYYY-MM-DD` (for example, `2023-10-31`). - - ## Supported versions - - Elasticsearch Serverless currently supports the following API versions: - - * `2023-10-31` - - Future breaking changes will introduce new date-based versions. - Support policies for existing versions will be announced when new versions are released. - - ## How to specify API versions - - Clients specify API versions using the `Elastic-Api-Version` HTTP header: - - ``` - GET /_search HTTP/1.1 - Elastic-Api-Version: 2023-10-31 - ``` - - ### Server responses - - The server's response depends on whether the client provides a version header: - - * When a client sends the `Elastic-Api-Version` header, the server processes the request using the specified API version or returns HTTP 400 if the version is unsupported or malformed. - * When no version header is provided, the server defaults to the latest supported API version. - - The server always includes the Elastic-Api-Version header in successful responses to indicate which version was used. + + ## API version format + + API versions use ISO8601 date format: `YYYY-MM-DD` (for example, `2023-10-31`). + + ## Supported versions + + Elasticsearch Serverless currently supports the following API versions: + + * `2023-10-31` + + Future breaking changes will introduce new date-based versions. + Support policies for existing versions will be announced when new versions are released. + + ## How to specify API versions + + Clients specify API versions using the `Elastic-Api-Version` HTTP header: + + ``` + GET /_search HTTP/1.1 + Elastic-Api-Version: 2023-10-31 + ``` + + ### Server responses + + The server's response depends on whether the client provides a version header: + + * When a client sends the `Elastic-Api-Version` header, the server processes the request using the specified API version or returns HTTP 400 if the version is unsupported or malformed. + * When no version header is provided, the server defaults to the latest supported API version. + + The server always includes the Elastic-Api-Version header in successful responses to indicate which version was used.