API (OpenAPI Contracts)

Status: Partial / contract governance active Source: src/Api/ Owner: API Contracts Guild

Purpose

src/Api/ is primarily an API-contract repository: it holds OpenAPI 3.1 specifications for StellaOps services, the aggregate composer, shared schema/parameter/response/security components, and the governance charter for API consistency.

src/Api ships no C# at all. It was previously not solely a specifications tree — the StellaOps.Api/ subfolder held loose, uncompiled ASP.NET Core controllers and a SignalR hub that no .csproj/.sln/.slnf referenced — but that scaffolding was removed in SPRINT_20260712_005 (DEAD-3). See the Controllers / Hubs — REMOVED entry in the Components section for the rationale and git-recovery pointer.

The aggregate spec is not automatically a shipped-contract claim. Per-service specs whose info.title contains (stub) or whose description is still a scaffold are draft stubs. The composer (compose.mjs) detects these via isDraftStubSpec() (title contains (stub) or description contains scaffold), marks the aggregate with x-stellaops-contract-status: contains-draft-stubs, and lists those services in x-stellaops-draft-services so DevPortal, SDK generation, and gateway consumers do not treat incomplete contracts as authoritative. When no draft stubs are present, the composer instead emits x-stellaops-contract-status: implemented.

Components

OpenAPI Specs — StellaOps.Api.OpenApi/

Per-service OpenAPI 3.1 YAML specifications:

As composed today, x-stellaops-draft-services lists: export-center, graph, jobengine, policy, scheduler.

Shared components — _shared/:

Aggregate spec:

Baselines:

Local guild docs:

Governance — StellaOps.Api.Governance/

This folder contains only the API Governance Guild charter (AGENTS.md) — its mission is lint rules, compatibility diff tooling, version-policy automation, and changelog generation. The charter is documentation; the actual tooling lives at the repo root, not inside this folder:

Controllers / Hubs — REMOVED (was StellaOps.Api/, uncompiled scaffolding)

src/Api/StellaOps.Api/ held 7 loose ASP.NET Core controllers plus a SignalR RemediationHub (namespaces StellaOps.Api.Controllers / StellaOps.Api.Hubs). No project ever compiled them — there was no .csproj anywhere under src/Api/, and no .sln/.slnf referenced them — so they never shipped and never served a route.

They were deleted in SPRINT_20260712_005 (DEAD-3) after a triple-check gate. The reason for removal was not merely tidiness: the files were decorated [ApiController] + [Authorize] and read like live, authorized endpoints (release promote/rollback, gate override, remediation execute), so a future contributor could plausibly have wired them up and exposed an unreviewed, un-tenant-checked surface. The real, live equivalents of those routes belong to their owning modules (ReleaseOrchestrator, Policy, Remediation, Telemetry) — consult those dossiers, not a resurrected copy of this scaffolding. Recoverable from git history if a design reference is ever needed.

src/Api therefore ships no C# at all. It is an OpenAPI contract repository (StellaOps.Api.OpenApi/) plus a documentation-only governance charter (StellaOps.Api.Governance/).

Usage

# Compose aggregate spec (preserves draft-stub markers)
npm run api:compose
# or directly:
node src/Api/StellaOps.Api.OpenApi/compose.mjs

# Lint OpenAPI specs (Spectral, ruleset at repo-root .spectral.yaml)
npm run api:lint

Heads-up (governance tooling is not implemented): api:lint and api:compose are the only functional API-governance commands. package.json previously also declared api:examples, api:compat, api:compat:test, and api:changelog, but their helper scripts (scripts/api-example-coverage.mjs, scripts/api-compat-diff.mjs, scripts/api-compat-diff.test.mjs, scripts/api-changelog.mjs) are absent — in fact the whole scripts/ directory is absent — so those four commands could only ever fail with MODULE_NOT_FOUND. They were removed from package.json in SPRINT_20260712_005 (DEAD-3) so the manifest stops advertising commands that cannot run. The only CI lanes that invoked them (.gitea/workflows-archived/{api-governance,oas-ci}.yml) are archived.

The capability (example-coverage check, compat diff, changelog generation) remains desirable and is still specified in ../../dev/contributing/api-contracts.md. Restoring it means writing the helper scripts and re-adding the npm aliases.