stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
1d962ee6fc98ad8c53715bbff6d513246f5b1361
git.stella-ops.org/docs/contributing/api-contracts.md
master 66cb6c4b8a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
feat: Add guild charters and task boards for various components 
- Introduced guild charters for Scanner Deno, PHP, Ruby, Native, WebService, Java, Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, UI, Zastava Observer, Zastava Webhook, Zastava Core, and Plugin Platform.
- Each charter outlines the mission, scope, required reading, and working agreements for the respective guilds.
- Created task boards for Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, and Zastava components to track progress and dependencies.
- Ensured all documents emphasize determinism, offline readiness, security, and integration with shared Surface libraries.
2025-11-01 02:21:46 +02:00

2.1 KiB
Raw Blame History

API Contract Contribution Guide

This guide explains how to propose, review, and publish API contract changes across StellaOps services. Follow these steps whenever you modify an OpenAPI specification or an externally supported endpoint.

1. Background

  • Public APIs are defined in src/Api/StellaOps.Api.OpenApi (aggregate spec) and per-service OpenAPI documents.
  • Compatibility checks run in CI via the API Governance tooling (StellaOps.Api.Governance).
  • Docs & SDK guilds consume the generated specs to publish references and SDK packages.

2. Workflow

  1. Design review – capture the proposed endpoint or schema change in the relevant module’s TASKS.md and link to any ADR or design doc.
  2. Spec update – modify the service-specific OpenAPI file under src/Api/StellaOps.Api.OpenApi/<service>/.
  3. Run governance checks – execute dotnet test src/Api/StellaOps.Api.Governance.Tests to validate lint rules, backwards compatibility, and examples.
  4. Regenerate aggregate spec – run dotnet run --project src/Api/StellaOps.Api.OpenApi to update stella.yaml.
  5. Update docs – adjust the corresponding module dossier (docs/modules/<component>/architecture.md or guides) to reflect new/changed endpoints.
  6. Notify SDK/Docs guilds – coordinate SDK regeneration (src/Sdk/StellaOps.Sdk.Generator) and release notes.

3. Backwards Compatibility Rules

  • Avoid breaking changes (removing endpoints/fields, altering semantics). If unavoidable, document deprecation timelines and fallback behaviour.
  • Additive changes (new optional fields, new endpoints) require version bump and changelog entry.
  • Error responses must remain structured; return application/problem+json payloads with stable error codes.

4. Tooling

  • dotnet tool run stellaops-api-lint – local lint.
  • dotnet run --project src/Api/StellaOps.Api.OpenApi -- --validate – schema validation.
  • docs/09_API_CLI_REFERENCE.md – update CLI reference when command behaviour shifts.

5. References

  • docs/modules/platform/architecture-overview.md
  • docs/modules/cli/architecture.md
  • src/Api/StellaOps.Api.Governance
  • src/Api/StellaOps.Api.OpenApi