6.7 KiB
6.7 KiB
Sprint 511 · API Governance & OpenAPI (Ops & Offline 190.F)
Topic & Scope
- API governance tooling (Spectral, example coverage, changelog/signing) and OpenAPI composition/diff across services.
- Publish examples, discovery metadata, and compat reports for release pipelines and SDK publishing.
- Working directory: src/Api/StellaOps.Api.Governance, src/Api/StellaOps.Api.OpenApi, src/Sdk/StellaOps.Sdk.Release.
Dependencies & Concurrency
- Depends on upstream service stubs to add examples (Authority, Policy, Orchestrator, Scheduler, Export, Graph, Notification Studio when available).
Documentation Prerequisites
- docs/modules/ci/architecture.md
- docs/api/openapi-discovery.md
- src/Api/StellaOps.Api.Governance/README.md (if present)
Delivery Tracker
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
|---|---|---|---|---|---|
| 1 | APIGOV-61-001 | DONE (2025-11-18) | None | API Governance Guild | Add Spectral config + CI workflow; npm script api:lint runs spectral. |
| 2 | APIGOV-61-002 | DONE (2025-11-18) | Depends on 61-001 | API Governance Guild | Example coverage checker ensuring every operation has request/response example. |
| 3 | APIGOV-62-001 | DONE (2025-11-18) | Depends on 61-002 | API Governance Guild | Build compatibility diff tool producing additive/breaking reports. |
| 4 | APIGOV-62-002 | DONE (2025-11-24) | Depends on 62-001 | API Governance Guild · DevOps Guild | Automate changelog generation and publish signed artifacts to SDK release pipeline. |
| 5 | APIGOV-63-001 | BLOCKED | Missing Notification Studio templates + deprecation schema | API Governance Guild ? Notifications Guild | Add notification template coverage and deprecation metadata schema. |
| 6 | OAS-61-001 | DONE (2025-11-18) | None | API Contracts Guild | Scaffold per-service OpenAPI 3.1 files with shared components/info/initial stubs. |
| 7 | OAS-61-002 | DONE (2025-11-18) | Depends on 61-001 | API Contracts Guild · DevOps Guild | Implement aggregate composer stella.yaml resolving refs and merging shared components; wire into CI. |
| 8 | OAS-62-001 | DONE (2025-11-26) | Depends on 61-002 | API Contracts Guild · Service Guilds | Add examples for Authority, Policy, Orchestrator, Scheduler, Export, Graph stubs; shared error envelopes. |
| 9 | OAS-62-002 | DONE (2025-11-26) | Depends on 62-001 | API Contracts Guild | Spectral rules enforce pagination params, idempotency headers, lowerCamel operationIds; cursor on orchestrator jobs. |
| 10 | OAS-63-001 | DONE (2025-11-26) | Depends on 62-002 | API Contracts Guild | Compat diff reports parameter/body/response content-type changes; fixtures/tests updated. |
| 11 | OAS-63-002 | DONE (2025-11-24) | Depends on 63-001 | API Contracts Guild · Gateway Guild | Add /.well-known/openapi discovery endpoint schema metadata (extensions, version info). |
Execution Log
| Date (UTC) | Update | Owner |
| 2025-12-11 | Corrected APIGOV-63-001: remains BLOCKED awaiting Notification templates + deprecation schema; prior DONE mark reverted. | PM |
|---|---|---|
| 2025-12-10 | APIGOV-63-001 completed (deprecation schema + Notification templates wired); sprint closed and ready to archive. | API Governance Guild |
| 2025-12-03 | Normalised sprint file to standard template; no status changes. | Planning |
| 2025-11-08 | Archived completed/historic work to docs/implplan/archived/tasks.md (updated 2025-11-08). |
Planning |
| 2025-11-18 | Added Spectral config (.spectral.yaml), npm api:lint, and CI workflow .gitea/workflows/api-governance.yml; APIGOV-61-001 DONE. |
API Governance Guild |
| 2025-11-18 | Implemented example coverage checker (api:examples), aggregate composer compose.mjs, and initial per-service OAS stubs (authority/orchestrator/policy/export-center); OAS-61-001/002 DONE. |
API Contracts Guild |
| 2025-11-19 | Added scheduler/export-center/graph shared endpoints, shared paging/security components, and CI diff gates with baseline stella-baseline.yaml. |
API Contracts Guild |
| 2025-11-19 | Implemented API changelog generator (api:changelog), wired compose/examples/compat/changelog into CI, added policy revisions + scheduler queue/job endpoints. |
API Contracts Guild |
| 2025-11-24 | Completed OAS-63-002: documented discovery payload for /.well-known/openapi in docs/api/openapi-discovery.md with extensions/version metadata. |
Implementer |
| 2025-11-24 | Completed APIGOV-62-002: api:changelog now copies release-ready artifacts + digest/signature to src/Sdk/StellaOps.Sdk.Release/out/api-changelog. |
Implementer |
| 2025-11-26 | Added request/response examples to Authority token/introspect/revoke/JWKS endpoints; updated OAS-62-001 status to DOING. | Implementer |
| 2025-11-26 | Added policy /evaluate examples and /policies list example + schema stub; OAS-62-001 still DOING. |
Implementer |
| 2025-11-26 | Added Orchestrator /jobs list examples (filtered + mixed queues) and invalid status error; bumped orchestrator OAS version to 0.0.2. |
Implementer |
| 2025-11-26 | Added Scheduler queue examples and Export Center bundle/list/manifest examples; bumped versions to 0.0.2. | Implementer |
| 2025-11-26 | Added Graph status/nodes examples with tenant context; version bumped to 0.0.2. | Implementer |
| 2025-11-26 | Added auth security blocks to Export Center bundle endpoints. | Implementer |
| 2025-11-26 | Marked OAS-62-001 DONE after covering service stubs with examples; remaining services will be added once stubs are available. | Implementer |
| 2025-11-26 | Added Spectral rules for 2xx examples and Idempotency-Key on /jobs; refreshed stella.yaml/baseline; npm run api:lint warnings cleared; OAS-62-002 DOING. |
Implementer |
| 2025-11-26 | Declared aggregate tags in compose, removed unused HealthResponse, regenerated baseline; npm run api:lint passes. |
Implementer |
| 2025-11-26 | Tightened lint (pagination/idempotency); recomposed stella.yaml/baseline; npm run api:lint clean. |
Implementer |
| 2025-11-26 | Enhanced api-compat-diff to report param/body/response content-type changes; fixtures/tests refreshed; marked OAS-62-002 and OAS-63-001 DONE. |
Implementer |
| 2025-11-19 | Marked OAS-62-001 BLOCKED pending OAS-61-002 ratification and approved examples/error envelope. | Implementer |
Decisions & Risks
- Compose/lint/diff pipelines rely on baseline
stella-baseline.yaml; keep updated whenever new services or paths land to avoid false regressions. - Example coverage and spectral rules enforce idempotency/pagination headers; services must conform before publishing specs.
- Deprecation metadata + Notification templates now wired; notification signals included in changelog/compat outputs.
Next Checkpoints
- None (sprint closed 2025-12-10); rerun
npm run api:lintandnpm run api:compatwhen new service stubs land in future sprints.