git.stella-ops.org/docs/api/versioning.md

API Versioning

Last updated: 2025-11-25 (Docs Tasks Md.V)

Principles

• Semantic versioning: OpenAPI artifacts follow MAJOR.MINOR.PATCH where breaking changes bump MAJOR, additive changes bump MINOR, fixes/docs bump PATCH.
• Long-lived compatibility: At least N-1 major versions remain runnable for 12 months; minor versions remain compatible for 6 months after release unless a security fix requires earlier removal.
• Explicit deprecations: Every breaking removal/change is preceded by a deprecation window with headers and changelog entries.
• Deterministic specs: Generated out/api/*.yaml are reproducible from a pinned manifest and committed checksums.

How versions are expressed

• Base URL: /api/v{major}/... (e.g., /api/v1/policy). Major only; minor/patch controlled via headers.
• Headers:
  • X-Stella-Api-Version: <major.minor.patch> → client-requested minor/patch; server chooses the highest compatible available ≤ requested. If omitted, server serves the latest compatible minor/patch for that major.
  • Deprecation: true + Sunset: <rfc7231-date> returned when an endpoint or field is scheduled for removal.
  • X-Stella-Api-Deprecated-Fields: field1,field2 lists soon-to-be-removed members for the response.
• Error codes:
  • error.code = API_VERSION_UNSUPPORTED when requested major is not served.
  • error.code = API_VERSION_TOO_OLD when requested minor/patch is below the minimum supported for the major.

Compatibility rules

• Additive changes (new fields/enums/paths) are allowed within the same major; fields default to null/empty and must not change meaning.
• Breaking changes require a new major: field removals/renames, required field additions, behavior changes that alter contracts.
• Enum extensions: existing values remain; new values must be tolerated by clients.
• Pagination/order: sort keys and determinism must be preserved across versions.

Release & lifecycle

1. Draft OpenAPI in src/Api/StellaOps.Api.OpenApi and update out/api/stella.yaml.
2. Run pnpm api:lint + pnpm api:compat --baseline stella-baseline.yaml to ensure no unintended breaks.
3. Publish changelog entry under out/api/changelog/<yyyyMMdd>-<version>.md with checksums/signature.
4. Announce deprecations via release notes; include Deprecation/Sunset headers in affected endpoints for at least 60 days before removal.
5. Sunset execution: remove endpoints/fields only after the sunset date and after the major bump ships.

Client guidance

• Always send X-Stella-Api-Version to lock to a tested minor/patch; pin SDK versions accordingly.
• Handle Deprecation/Sunset headers by warning users and planning upgrades.
• Prefer server-provided pagination tokens; avoid relying on incidental field order.

Testing

• Contract tests must cover the lowest and highest supported minor/patch for each major.
• Deterministic fixtures for each version live under tests/fixtures/api/versioning/; CI runs pnpm api:compat against these fixtures.
• Compatibility diff (pnpm api:compat old.yaml new.yaml) now flags:
  • Added/removed operations and responses
  • Parameter additions/removals/requiredness flips
  • Request body additions/removals/requiredness and content-type changes
  • Response content-type additions/removals Use --fail-on-breaking in CI to block removals/requiredness increases.