master
66cb6c4b8a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- 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.
38 lines
2.1 KiB
Markdown
38 lines
2.1 KiB
Markdown
# 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`
|