[Proposal] API Resource Version Format and Version Grouping

[renuka-fernando]

Summary

• Enforce strict vMAJOR.MINOR version format (^v\d+\.\d+$) across all API resource types
• Introduce a new spec.versionGroup field as the stable grouping identity that ties versions of the same logical API together
• Demote spec.displayName to a pure presentation label that can be freely renamed without affecting identity or grouping
• Change the grouping uniqueness constraint from (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. The vMAJOR.MINOR format is the sweet spot — major for breaking changes requiring consumer migration, minor for additions and non-breaking changes.

Problem 2: displayName Conflates Presentation and Identity

Currently, versions of the same logical API are grouped by matching displayName values, with a uniqueness constraint on (kind, displayName, version, gatewayId) to prevent duplicates.

This creates several issues:

• Renaming breaks grouping. Changing displayName from "Weather-API" to "Weather Service" on one version but not another silently breaks the version lineage.
• Semantic overload. One field serves both display/presentation AND identity/grouping — purposes that have different lifecycle requirements.
• No explicit relationship. There is no dedicated field that declares "these resources are versions of the same logical API." The grouping is entirely implicit through matching display names, which is fragile.

Proposal

1. Strict Version Format

• Enforce the regex ^v\d+\.\d+$ across all resource types (RestApi, LlmProvider, LlmProxy, Mcp, WebSubApi)
• The v prefix is mandatory — it is idiomatic for API versioning and removes ambiguity between 1.0 and v1.0
• Both major and minor segments are required — v1 is rejected, must be v1.0
• No normalization, no shorthand acceptance — users must provide the exact format

The invocation URL is orthogonal to the version. The spec.context field 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 the spec.version value. 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.versionGroup

• Add spec.versionGroup as a new required field on all deployable resource schemas
• Use kind + versionGroup as the grouping key (e.g., an LlmProxy and LlmProvider can both have versionGroup: OpenAI — they are separate groups)
• versionGroup is mutable — users can update it to move a resource to a different group (the uniqueness constraint still prevents conflicts)
• Demote displayName to optional — when omitted, UIs fall back to versionGroup

The field name versionGroup was chosen after considering several alternatives (see Alternatives section). It is self-documenting, reads naturally paired with version, does not collide with metadata.name or K8s apiGroup, and produces clear grouping keys in logs and error messages: Weather-API:v1.0.

Field Definitions

New field added to all resource spec schemas:

versionGroup:
  type: string
  required: true
  description: >
    Grouping identity for the resource. Resources with the same versionGroup are considered versions of the same logical kind.
  minLength: 1
  maxLength: 100
  pattern: '^[a-zA-Z0-9\-_\.]+$'
  example: Weather-API

Version field validation tightened:

version:
  type: string
  description: >
    API version in vMAJOR.MINOR format. The v prefix is mandatory.
  pattern: '^v\d+\.\d+$'
  example: v1.0

Examples

Before (current):

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: weather-api-v1
spec:
  displayName: Weather-API        # Used for BOTH grouping AND display
  version: v1                     # Ambiguous: is this v1.0? v1.0.0?
  context: /weather/v1
  upstream:
    main:
      url: http://weather-backend:5000
  operations:
    - method: GET
      path: /forecast
---
apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: weather-api-v1.0
spec:
  displayName: Weather-API        # Must match exactly or grouping breaks
  version: v1.0                   # Is this the same as v1 above? Unclear
  context: /weather/v1.0
  upstream:
    main:
      url: http://weather-backend:5000
  operations:
    - method: GET
      path: /forecast

After (proposed):

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: weather-api-v1-0          # Unique CR handle (K8s identity)
spec:
  versionGroup: Weather-API       # Stable grouping identity
  displayName: "Weather Service"  # Optional, free-form presentation label
  version: v1.0                   # Enforced vMAJOR.MINOR format
  context: /weather/v1.0          # Invocation path (independent)
  upstream:
    main:
      url: http://weather-backend:5000
  operations:
    - method: GET
      path: /forecast
---
apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: weather-api-v1-1
spec:
  versionGroup: Weather-API       # Same group -- these are versions of one API
  displayName: "Weather Service"  # Can differ per version, no impact on identity
  version: v1.1                   # Clear minor bump
  context: /weather/v1.1
  upstream:
    main:
      url: http://weather-backend:6000
  operations:
    - method: GET
      path: /forecast
    - method: GET
      path: /historical

Drawbacks

• Breaking change for version format: Existing resources using v1, 1.0, or v1.0.0 formats will fail validation. Users must update all versions to the strict vx.x format.
• New required field: All existing YAML configurations need a versionGroup field added. This is a schema-level breaking change.

Alternatives Considered

Alternative 1: Keep Flexible Version Format with Auto-Normalization

• What: Accept all current formats but normalize internally (e.g., v1 -> v1.0, 1.0 -> v1.0)
• Pros: No breaking changes for existing users; more ergonomic input
• Cons: Users see different versions than what they submitted; equivalence rules are surprising; hidden behavior makes debugging harder
• Why rejected: Hidden normalization creates a mismatch between what users write and what the system stores. Strict enforcement is more explicit and predictable

Alternative 2: Full SemVer (vMAJOR.MINOR.PATCH)

• What: Require strict three-segment semantic versioning
• Pros: Well-understood standard; natural ordering
• Cons: Patch versions are semantically meaningless for API versioning — a backend bug fix should not create a new API version; overly verbose for the typical use case
• Why rejected: The patch segment adds complexity without value for API consumers

Alternative 3: Keep displayName for Grouping with Stricter Validation

• What: Instead of adding versionGroup, add validation that prevents displayName from changing across versions
• Pros: No new fields; no schema migration
• Cons: Permanently conflates presentation and identity; surprising restriction ("why can't I rename my API?")
• Why rejected: A field named "displayName" should be freely changeable — restricting it contradicts its purpose

Alternative 4: spec.name or spec.apiName as the Grouping Field

• What: Use spec.name or spec.apiName instead of spec.versionGroup
• Pros: Simpler field name; aligns with the {name}/{version} pattern
• Cons: Confusion with metadata.name is a real onboarding risk — two "name" fields in the same resource causes cognitive friction; doesn't convey the versioning relationship
• Why rejected: The ambiguity cost outweighs the simplicity benefit

Alternative 5: spec.apiFamily or spec.group

• What: Use an alternative grouping field name
• Pros: apiFamily has strong grouping semantics; group is concise
• Cons: apiFamily only makes sense for RestApi, not LlmProvider or Mcp; group conflicts with the Kubernetes API group concept
• Why rejected: Neither name works well across all resource types and deployment contexts

Compatibility

• Backwards compatible?: No — two breaking changes: (1) version format restriction rejects previously-accepted formats; (2) versionGroup is a new required field