API Versioning

How Stella Ops versions its OpenAPI contracts and SDKs, declares deprecations, and keeps specs deterministic and reproducible. This page is for API consumers planning upgrades and for maintainers evolving the contracts; for the wider contract/SDK programme see SDK & OpenAPI Program, and for shared request conventions see the API Overview.

Last updated: 2026-05-30 (deep doc↔code reconciliation against src/Api/StellaOps.Api.OpenApi)

Implementation status. Parts of this page describe a target design that is not yet wired up in the repository. Where a mechanism is aspirational it is marked (PROPOSED — not implemented) so consumers do not depend on it. The composer (compose.mjs) is real and runs; the lint/compat/changelog scripts referenced from package.json (api:lint, api:examples, api:compat, api:compat:test, api:changelog) currently point at scripts/api-*.mjs files that are not present in the tree, and the driving CI workflows live under .gitea/workflows-archived/. Treat those steps as the intended pipeline rather than a guaranteed-green build until the scripts are restored.

Principles

• Semantic versioning: OpenAPI artifacts follow MAJOR.MINOR.PATCH[-PRERELEASE] where breaking changes bump MAJOR, additive changes bump MINOR, fixes/docs bump PATCH, and freeze candidates carry a prerelease tag (e.g. 0.1.0-alpha). The aggregate spec is currently 0.0.1 (unfrozen); per-service specs version independently (Authority 0.1.1, Scanner 1.0.0, Policy/Scheduler 0.0.3, Graph/JobEngine/Export Center 0.0.2).
• 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. (PROPOSED — not implemented): no supported-version window is enforced in code today.
• Explicit deprecations: Every breaking removal/change is preceded by a deprecation window. The enforced mechanism is the x-deprecation OpenAPI extension on the operation (see Deprecations), checked by Spectral rules; standard Deprecation/Sunset HTTP response headers are the runtime signal.
• Deterministic specs: The generated src/Api/StellaOps.Api.OpenApi/stella.yaml aggregate is reproducible from per-service specs via compose.mjs (stable ordering of paths, schemas, parameters, responses; no timestamps in the body). SDK freezes pin a committed SHA256 of stella.yaml (see Release & lifecycle).

How versions are expressed

• Aggregate spec: a single composed document at src/Api/StellaOps.Api.OpenApi/stella.yaml. info.version is the aggregate API version (0.0.1). The composer also emits two extensions used to flag maturity:
  • x-stellaops-contract-status: implemented or contains-draft-stubs.
  • x-stellaops-draft-services: list of service specs detected as scaffold/stub (currently export-center, graph, jobengine, policy, scheduler). A spec is treated as a draft stub when its info.title contains (stub) or its info.description contains scaffold.
• Per-service base URLs: there is no uniform /api/v{major}/... convention across services. In practice the version is carried in different ways:
  • Server URL with no version path (e.g. https://authority.stellaops.local).
  • Server URL embedding the version (e.g. Scanner: https://scanner.stellaops.local/api/v1).
  • Versioned path prefixes on individual operations (e.g. Policy exceptions: /api/v1/exceptions, /api/v1/exceptions/{exceptionId}).
• Headers (PROPOSED — not implemented):
  • X-Stella-Api-Version: <major.minor.patch> (client-requested minor/patch negotiation) is not present in any spec or service in src/. Minor/patch negotiation via request header is design intent only.
  • X-Stella-Api-Deprecated-Fields: field1,field2 is not emitted anywhere in code.
  • Deprecation + Sunset response headers are the standard runtime deprecation signal. They are described in the DeprecationSummary schema (_shared/schemas/deprecation.yaml) but are not yet asserted in the per-service operation specs.
• Error codes (PROPOSED — not implemented): API_VERSION_UNSUPPORTED and API_VERSION_TOO_OLD do not exist anywhere in src/. There is no version-negotiation error contract today; errors use the standard envelope (error.code, error.message, trace_id) from the shared response components.

Deprecations

Deprecation is declared per-operation in the per-service OpenAPI files and enforced by Spectral rules (.spectral.yaml at the repo root):

• Mark the operation deprecated: true and attach an x-deprecation object. The schema is DeprecationMetadata in src/Api/StellaOps.Api.OpenApi/_shared/schemas/deprecation.yaml.
• Required x-deprecation fields (rule stella-deprecated-has-metadata, severity error): deprecatedAt (date-time), sunsetAt (date-time), successorPath, reason.
• Optional fields: successorOperationId, migrationGuide (uri; recommended by hint rule stella-deprecated-migration-guide), notificationChannels (slack | teams | email | webhook; recommended by hint rule stella-deprecated-notification-channels), affectedConsumerHints, breakingChanges[].
• stella-deprecated-sunset-future (warn) flags sunset dates that have already passed.
• Downstream consumers of this metadata: changelog generation, SDK publishing, and Notify-service deprecation events (DeprecationNotificationEvent, event type api.deprecation.announced; DeprecationReport for aggregated reporting).

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. Collection list/search endpoints expose limit/cursor query parameters (Spectral rule stella-pagination-params); state-changing 201/202 operations accept an Idempotency-Key header (rule stella-idempotency-header).

Release & lifecycle

1. Edit the per-service spec under src/Api/StellaOps.Api.OpenApi/<service>/openapi.yaml, then regenerate the aggregate: npm run api:compose (which runs node src/Api/StellaOps.Api.OpenApi/compose.mjs and overwrites src/Api/StellaOps.Api.OpenApi/stella.yaml).
2. Run lint + compatibility checks (all via npm run, not pnpm):
   • npm run api:lint — Spectral lint of src/Api/StellaOps.Api.OpenApi/**/*.yaml (rules in root .spectral.yaml).
   • npm run api:examples — example coverage check.
   • npm run api:compat — runs node scripts/api-compat-diff.mjs. The CI invocation is positional: node scripts/api-compat-diff.mjs <old.yaml> <new.yaml> --output text [--fail-on-breaking]. CI compares against the previous commit’s stella.yaml and against the baseline at src/Api/StellaOps.Api.OpenApi/baselines/stella-baseline.yaml. (There is no --baseline <file> flag; the baseline is passed as the <old.yaml> positional argument.)
   • npm run api:changelog — regenerates src/Api/StellaOps.Api.OpenApi/CHANGELOG.md (sections: Additive Operations, Breaking Operations).

   Status: the scripts/api-*.mjs helpers are not present in the repository (the whole scripts/ directory is absent); only compose.mjs is committed. Because the api:examples/api:compat/api:compat:test/api:changelog npm aliases could therefore only fail, they were removed from package.json in SPRINT_20260712_005 (DEAD-3); api:lint and api:compose remain and work. Restoring this step means writing the helper scripts and re-adding the npm aliases.

3. Changelog lives in-tree at src/Api/StellaOps.Api.OpenApi/CHANGELOG.md. (PROPOSED — not implemented): a per-release out/api/changelog/<yyyyMMdd>-<version>.md with embedded checksum/signature is design intent and does not exist; there is no out/api/ directory.
4. Announce deprecations via release notes and the x-deprecation metadata above; standard Deprecation/Sunset headers should accompany affected endpoints for the configured deprecation window before removal.
5. SDK freeze: tag the commit api/v{version} (e.g. api/v0.1.0-alpha), compute and commit the SHA256 of stella.yaml (sha256sum stella.yaml > stella.yaml.sha256), and have SDK generators validate it via STELLA_OAS_EXPECTED_SHA256. See the API governance baseline.
6. Sunset execution: remove endpoints/fields only after the sunset date and after the major bump ships.

Client guidance

• Pin SDK versions to a frozen aggregate-spec SHA256 (STELLA_OAS_EXPECTED_SHA256); the generated SDKs validate the hash before use.
• Honor standard Deprecation/Sunset response headers by warning users and planning upgrades; consult the operation’s x-deprecation.successorPath/migrationGuide for the replacement.
• Prefer server-provided pagination tokens (cursor); avoid relying on incidental field order.
• (PROPOSED — not implemented): do not yet rely on an X-Stella-Api-Version request header for minor/patch negotiation — no service consumes it.

Testing

• The intended contract test is npm run api:compat:test (node scripts/api-compat-diff.test.mjs), which exercises the compat differ for: added/removed operations and responses; parameter additions/removals/requiredness flips; request body additions/removals/requiredness and content-type changes; response content-type additions/removals. CI uses --fail-on-breaking to block removals/requiredness increases.
• Status: as above, scripts/api-compat-diff.test.mjs and scripts/api-compat-diff.mjs are not present in the tree; the test step is currently inert until restored.
• (PROPOSED — not implemented): the fixture directory tests/fixtures/api/versioning/ does not exist. CI today derives its comparison inputs from git history (previous commit’s stella.yaml) and the committed baseline (src/Api/StellaOps.Api.OpenApi/baselines/stella-baseline.yaml) rather than from a versioning fixture set.