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)

PCD-460 Policy examples, 11b3e6f5ec (2026-10-08). The operation prefixes, bodies and scopes below were checked against the composed Policy host. Other artifact/version details retain their dated review. Recheck Program.cs, ExceptionEndpoints.cs, ExceptionApprovalEndpoints.cs and their request DTOs before treating these source contracts as current installation behavior.

Until the first external install, cutovers remove predecessor routes in the same change that verifies their replacement; there is no legacy alias or deprecation window. The multi-version/deprecation-window material below is post-install design, not authorization to retain unsupported pre-release contracts. Forward-only migrations keep their separate immutable-history rule.

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 present, and package.json retains api:compose and api:lint. The former example/compatibility/changelog helpers and aliases are absent; the driving governance workflow is archived under .gitea/workflows-archived/. Those compatibility steps are design history, not a current enforced pipeline.

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 (post-install design): The proposed window uses the x-deprecation OpenAPI extension (see Deprecations). Spec metadata and lint rules do not establish a runtime header or authorize a pre-release alias.
• 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).
  • Operation-specific prefixes: Policy exception lifecycle reads use the unversioned /api/policy/exceptions and /api/policy/exceptions/{id}. The distinct approval workflow uses /api/v1/policy/exception/request and /api/v1/policy/exception/requests; these are not aliases or interchangeable request bodies.

Current Policy examples (source publication, not deployment acceptance):

Both groups require tenant context. The host maps both explicitly. Their different DTOs, scopes and lifecycle/approval semantics prevent a mechanical prefix swap.

• 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 are proposed version-negotiation codes. Shared response components describe an error envelope, but individual owner operations define their actual error bodies; the Policy detail example above returns Problem Details rather than that envelope.

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. Post-install design: announce deprecations through release notes and reviewed metadata; runtime headers require an implemented owner contract. This step does not apply a pre-release compatibility window.
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. Post-install design: execute the recorded sunset after its release gate. Pre-release cutovers use the same-change withdrawal rule stated above.

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.