stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
582a88e8f8ddf9e03bf1a0cff65f619bf4306ea1
git.stella-ops.org/docs/implplan/SPRINT_0511_0000_0001_api.md
StellaOps Bot 582a88e8f8
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Export Center CI / export-ci (push) Has been cancelled
Details
Policy Simulation / policy-simulate (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
Signals CI & Image / signals-ci (push) Has been cancelled
Details
feat(docs): Add sprint documentation for CLI and API governance 
- Created documentation for Sprint 200, 202, 203, 204, and 205 focusing on CLI enhancements and SDKs.
- Normalized legacy filenames to prevent divergent updates.
- Documented completed tasks, dependencies, and active items for CLI commands related to observability, orchestration, packaging, and policy management.
- Implemented API governance tooling and OpenAPI composition for Sprint 511, detailing task statuses and dependencies.
- Updated legacy web sprint documentation to reflect new naming conventions and standard templates.
2025-12-06 00:41:59 +02:00

6.9 KiB
Raw Blame History

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).
  • APIGOV-63-001 blocked on Notification Studio templates and deprecation metadata schema.

Documentation Prerequisites

  • docs/modules/ci/architecture.md
  • docs/api/openapi-discovery.md
  • src/Api/StellaOps.Api.Governance/README.md (if present)

BLOCKED Tasks: Before working on BLOCKED tasks, review BLOCKED_DEPENDENCY_TREE.md for root blockers and dependencies.

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-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

  • APIGOV-63-001 blocked until Notification Studio templates and deprecation metadata schema are delivered; downstream changelog/compat outputs must note missing notification metadata.
  • 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.

Next Checkpoints

  • Receive Notification Studio templates/deprecation schema to unblock APIGOV-63-001 and add notification examples.
  • Re-run npm run api:lint and npm run api:compat after next service stub additions to refresh baseline and changelog artifacts.