From 6851ca298811c9a21f205e190b942101e2b67b2b Mon Sep 17 00:00:00 2001 From: Austin Pond Date: Tue, 21 Oct 2025 09:22:28 -0400 Subject: [PATCH] Docs: Add Additional `/apis` Versioning Guidance (#109134) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [docs] Add extra guidance for new /apis versioning. * Fix typo * fix typo * Run prettier on changes. * Update docs/sources/developers/http_api/apis.md Co-authored-by: Igor Suleymanov * Update docs/sources/developers/http_api/apis.md Co-authored-by: Igor Suleymanov * Update docs/sources/developers/http_api/apis.md Co-authored-by: Igor Suleymanov * Run prettier on doc --------- Co-authored-by: Irene Rodríguez Co-authored-by: Igor Suleymanov --- docs/sources/developers/http_api/apis.md | 26 +++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/sources/developers/http_api/apis.md b/docs/sources/developers/http_api/apis.md index c00d34b4de7..5dc90cba139 100644 --- a/docs/sources/developers/http_api/apis.md +++ b/docs/sources/developers/http_api/apis.md @@ -42,11 +42,27 @@ Groups organize related functionality into logical collections. For example `das These APIs will also uses semantic versioning with three stability levels: -| Level | Format | Description | Use Case | -| ----- | ---------- | --------------------------------------------------------------------------- | ------------------------ | -| Alpha | `v1alpha1` | Early development stage. Unstable, may contain bugs, and subject to removal | For testing new features | -| Beta | `v1beta1` | More stable than alpha, but may still have some changes | For early production use | -| GA | `v1` | Generally Available. Stable with backward compatibility guarantees | For production use | +| Level | Format | Description | Use Case | Enabled By Default? | +| ----- | ---------- | --------------------------------------------------------------------------- | ------------------------ | ------------------- | +| Alpha | `v1alpha1` | Early development stage. Unstable, may contain bugs, and subject to removal | For testing new features | No | +| Beta | `v1beta1` | More stable than alpha, but may still have some changes | For non-critical use | No | +| GA | `v1` | Generally Available. Stable with backward compatibility guarantees | For production use | Yes | + +#### Alpha + +Alpha versions should not be served unless explicitly enabled by a feature flag, and should be considered completely experimental and subject to major changes. +An alpha version may undergo breaking changes without adding an additional version, and should not be relied upon by production workflows. Alpha versions may be removed completely, even without being promoted to a more stable level (e.g. an experimental API may be introduced as alpha for a new feature and subsequently removed completely, in case that feature gets canceled). + +#### Beta + +Beta versions should not contain breaking changes in the schema, but still may be subject to changes in handling logic or semantics. +Breaking schema changes require a new published beta version (such as publishing `v1beta2` for breaking changes to the `v1beta1` schema). +While beta versions are no longer considered experimental like alpha versions, they should still be disabled by default. + +#### GA + +GA versions are enabled by default, and can be treated as completely stable. The only changes that can be made to these APIs are bug fixes, +and any other changes should instead result in a new published version of the API. ### Namespace (``)