[Proposal] API Resource Version Format and Version Grouping #1294
renuka-fernando
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Summary
vMAJOR.MINORversion format (^v\d+\.\d+$) across all API resource typesspec.versionGroupfield as the stable grouping identity that ties versions of the same logical API togetherspec.displayNameto a pure presentation label that can be freely renamed without affecting identity or grouping(kind, displayName, version, gatewayId)to(kind, versionGroup, version, gatewayId)Note on identity vs grouping: The resource identity is
kind+metadata.name— this uniquely identifies a single resource. The(kind, versionGroup, version)tuple is not an identity key — it is a grouping key with a uniqueness constraint to prevent duplicate versions within the same logical API group.Motivation
Problem 1: Version Format Ambiguity
The current version validation accepts
v1,v1.0,v1.0.0,1,1.0, and more. This means a user can create "Weather API v1" and "Weather API v1.0" as two separate resources — causing confusion, making version listings unpredictable, and producing duplicate entries for what should be the same API.Additionally, patch versions (
vx.x.x) do not make sense for API versioning. A backend bug fix should not require consumers to migrate to a new API version. If a change is breaking, it warrants a minor or major bump.Industry convention supports this: Google, Stripe, GitHub, and OpenAI all expose major-only versions (
v1). Enterprise APIs sometimes use major.minor. ThevMAJOR.MINORformat is the sweet spot — major for breaking changes requiring consumer migration, minor for additions and non-breaking changes.Problem 2:
displayNameConflates Presentation and IdentityCurrently, versions of the same logical API are grouped by matching
displayNamevalues, with a uniqueness constraint on(kind, displayName, version, gatewayId)to prevent duplicates.This creates several issues:
displayNamefrom "Weather-API" to "Weather Service" on one version but not another silently breaks the version lineage.Proposal
1. Strict Version Format
^v\d+\.\d+$across all resource types (RestApi, LlmProvider, LlmProxy, Mcp, WebSubApi)vprefix is mandatory — it is idiomatic for API versioning and removes ambiguity between1.0andv1.0v1is rejected, must bev1.0The invocation URL is orthogonal to the version. The
spec.contextfield defines the base path used for routing (e.g.,/weather/v1.0,/weather/v1,/weather). It is configured independently and does not need to match or embed thespec.versionvalue. The version field is for identifying and grouping API resources — the context path is for routing. Users are free to design their URL scheme however they want regardless of the version format.2. Version Grouping with
spec.versionGroupspec.versionGroupas a new required field on all deployable resource schemaskind+versionGroupas the grouping key (e.g., anLlmProxyandLlmProvidercan both haveversionGroup: OpenAI— they are separate groups)versionGroupis mutable — users can update it to move a resource to a different group (the uniqueness constraint still prevents conflicts)displayNameto optional — when omitted, UIs fall back toversionGroupThe field name
versionGroupwas chosen after considering several alternatives (see Alternatives section). It is self-documenting, reads naturally paired withversion, does not collide withmetadata.nameor K8sapiGroup, and produces clear grouping keys in logs and error messages:Weather-API:v1.0.Field Definitions
New field added to all resource spec schemas:
Version field validation tightened:
Examples
Before (current):
After (proposed):
Drawbacks
v1,1.0, orv1.0.0formats will fail validation. Users must update all versions to the strictvx.xformat.versionGroupfield added. This is a schema-level breaking change.Alternatives Considered
Alternative 1: Keep Flexible Version Format with Auto-Normalization
v1->v1.0,1.0->v1.0)Alternative 2: Full SemVer (vMAJOR.MINOR.PATCH)
Alternative 3: Keep
displayNamefor Grouping with Stricter ValidationversionGroup, add validation that preventsdisplayNamefrom changing across versionsAlternative 4:
spec.nameorspec.apiNameas the Grouping Fieldspec.nameorspec.apiNameinstead ofspec.versionGroup{name}/{version}patternmetadata.nameis a real onboarding risk — two "name" fields in the same resource causes cognitive friction; doesn't convey the versioning relationshipAlternative 5:
spec.apiFamilyorspec.groupapiFamilyhas strong grouping semantics;groupis conciseapiFamilyonly makes sense for RestApi, not LlmProvider or Mcp;groupconflicts with the Kubernetes API group conceptCompatibility
versionGroupis a new required fieldBeta Was this translation helpful? Give feedback.
All reactions