APIConfiguration Version Management Strategy

[Tharsanan1]

Context

Following our discussion on resource type configuration and naming conventions, there's been a question about how we should manage versions as our specs evolve. Specifically:

"Should we update the version every time there is a spec change, or only when there's a breaking change?"

This proposal outlines a versioning strategy based on Kubernetes community best practices.

---

Proposed Approach: Version on Breaking Changes Only

I propose following the Kubernetes API versioning model where versions are bumped only for breaking/incompatible changes, not for every spec modification.

What This Means in Practice

No version bump needed for:

• Adding a new optional field (with a sensible default)
• Adding new enum values
• Relaxing validation constraints
• Bug fixes that don't alter the API contract
• Documentation updates

Version bump required for:

• Adding a required field
• Removing or renaming a field
• Changing a field's type
• Changing a field's meaning/behavior
• Maturity graduation (alpha → beta → stable)

---

Version Format

We'll use the standard Kubernetes versioning scheme:

v<major><stability><revision>

Stage	Format	Example
Alpha	v1alpha1, v1alpha2	Experimental, breaking changes expected
Beta	v1beta1, v1beta2	Pre-release, API stabilizing
Stable/GA	v1, v2	Production-ready, strong compatibility guarantees

---

Examples

✅ Adding an optional field — same version

# Before
apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
spec:
  basePath: /api
  targetUrl: "https://backend.example.com"

# After (still v1alpha1)
apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
spec:
  basePath: /api
  targetUrl: "https://backend.example.com"
  timeout: 30s  # New optional field, defaults to 30s

❌ Renaming a field — requires version bump

# v1alpha1
spec:
  targetUrl: "https://backend.example.com"

# v1alpha2 (bumped due to rename)
spec:
  targetEndpoint: "https://backend.example.com"

❌ Adding a required field — requires version bump

# v1alpha1
spec:
  basePath: /api

# v1alpha2 (bumped due to new required field)
spec:
  basePath: /api
  backendRef: my-backend  # Required, no default

---

Quick Decision Guide

Change Type	Bump Version?
New optional field with default	No
New required field	Yes
Field removed	Yes
Field renamed	Yes
Field type changed	Yes
Validation relaxed	No
Validation tightened	Yes
Bug fix (same contract)	No
Ready for beta/GA	Yes

---

Maturity Graduation

When a resource is ready to move to the next stability level, we bump the version accordingly:

v1alpha1 → v1alpha2 → v1beta1 → v1beta2 → v1

Each maturity level sets different expectations:

• Alpha: Expect breaking changes, not enabled by default
• Beta: API stabilizing, enabled by default, migration path provided for changes
• Stable (v1): Production-ready, no breaking changes without major version bump

---

Migration & Deprecation

When we do bump versions:

1. Document the changes and migration path clearly
2. Serve both old and new versions during a transition period
3. Provide at least 2 releases before removing the old version
4. Consider conversion webhooks if schema differs significantly

References

• Kubernetes API Versioning
• Kubernetes Deprecation Policy
• CRD Versioning Guide
• sig-architecture API Changes Guide