stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/contributing/api-contracts.md
StellaOps Bot 9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Signals CI & Image / signals-ci (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Policy Simulation / policy-simulate (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
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
devportal-offline / build-offline (push) Has been cancelled
Details
up
2025-11-25 22:09:44 +02:00

2.7 KiB
Raw Permalink Blame History

Contributing to API Contracts

Last updated: 2025-11-25

Scope

Guidelines for editing service OpenAPI specs, lint rules, compatibility checks, and release artefacts across StellaOps services.

Required tools

  • Node.js 20.x + pnpm 9.x
  • Spectral CLI (invoked via pnpm api:lint in src/Api/StellaOps.Api.OpenApi)
  • diff2html (optional) for human-friendly compat reports

Workflow (per change)

  1. Edit service OAS under src/Api/StellaOps.Api.OpenApi/services/<service>/*.yaml.
  2. Run lint + compose + compat + changelog from repo root: 
    pnpm --filter @stella/api-openapi api:lint       # spectral
pnpm --filter @stella/api-openapi api:compose    # build stella.yaml
pnpm --filter @stella/api-openapi api:compat     # compare against baseline
pnpm --filter @stella/api-openapi api:changelog  # generate digest/signature
  3. Review outputs:
    • out/api/stella.yaml (composed spec)
    • out/api/compat-report.json (+ .html if generated)
    • out/api/changelog/ (digest + signature for SDK pipeline)
  4. Update examples: ensure request/response examples exist for changed endpoints; add to examples/ directories.
  5. Commit changes with notes on breaking/additive results; attach compat report paths.

Lint rules (Spectral)

  • House rules live in .spectral.yaml under src/Api/StellaOps.Api.OpenApi.
  • Enforce: tagged operations, error envelope shape, schema refs reuse, pagination tokens, RBAC scopes, standard headers (traceparent, x-correlation-id).

Compatibility checks

  • Baseline file: stella-baseline.yaml (kept in repo under out/api/ and updated per release).
  • api:compat flags additive/breaking/unchanged deltas. Breaking changes require approval from API Governance Guild and affected service guilds.

Examples & error envelopes

  • Every operation must have at least one request + response example.
  • Error responses must use the standard envelope (error.code, error.message, trace_id).

Offline/air-gap

  • Keep pnpm-lock.yaml pinned; store node_modules/.pnpm cache in Offline Kit when needed.
  • Include composed spec, compat report, and changelog artefacts in offline bundles under offline/api/ with checksums.

Release handoff

  • Deliverables for each release:
    • out/api/stella.yaml
    • out/api/compat-report.json (+ .html if produced)
    • out/api/changelog/* (digest, signature, manifest)
  • Provide SHA256 checksums for artefacts and note source_commit + timestamp in release notes.

Review checklist

  • Lint clean (api:lint)
  • Examples present for changed endpoints
  • Compat report reviewed (additive/breaking noted)
  • Changelog artefacts generated + checksums
  • Offline bundle artefacts staged (if required)
  • Docs/UI/SDK owners notified of breaking changes