API Stability

Versioning

All KubeGlass API endpoints are versioned under /api/v1/. The version prefix is part of the URL path and incremented for breaking changes.

Level	Prefix	Guarantee
Stable	/api/v1/	No breaking changes within a major version
Beta	/api/v1beta1/	May change between minor releases. 1-release deprecation notice
Alpha	/api/v1alpha1/	No stability guarantee

All current endpoints are Stable.

Breaking vs. non-breaking changes

Breaking (requires major version bump)

• Removing an endpoint
• Removing or renaming a response field
• Changing a field’s type
• Changing the HTTP method
• Changing a required parameter’s meaning
• Changing an error code for a documented condition
• Changing authentication requirements

Non-breaking (may occur in any minor release)

• Adding new endpoints
• Adding optional response fields
• Adding optional query parameters
• Adding new error codes for undocumented conditions
• Changing human-readable error messages
• Adding values to enum-like fields
• Performance improvements

Deprecation policy

1. Response includes a Deprecation header with sunset date
2. Announced in release notes and CHANGELOG
3. At least two minor releases (~12–16 weeks) before removal
4. Deprecated endpoints return a Warning header with migration guidance

Response envelope

Success

{ "data": { ... } }

List endpoints:

{ "data": [ ... ], "total": 42 }

Error

{
  "error": "error_code",
  "message": "Human-readable description.",
  "requestId": "abc123-def456"
}

See Error Codes for all machine-readable codes.

Content type

All endpoints accept and return application/json. WebSocket endpoints use the standard upgrade handshake.

Rate limiting

Mutation endpoints: 100 req/s per IP, burst 200. Rate-limited responses return HTTP 429 with Retry-After header.

Pagination

Parameter	Default	Max	Description
limit	100	1000	Items per page
continue	-	-	Continuation token

ETag caching

Responses include ETag headers. Send If-None-Match to receive HTTP 304 for unchanged resources.