52 lines
3.5 KiB
Markdown
52 lines
3.5 KiB
Markdown
# SDK & OpenAPI Program
|
||
|
||
> Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||
|
||
## Overview
|
||
|
||
The SDK & OpenAPI program delivers canonical OpenAPI 3.1 contracts for every Stella Ops surface, plus officially supported SDKs (TypeScript/Node, Python, Go, Java, C#). It ensures backwards-compatible evolution, documentation, and offline availability.
|
||
|
||
- **Primary components:** API Gateway, Web Services, Policy Engine, Conseiller, Excitator, Orchestrator, Findings Ledger, Export Center, Authority & Tenancy, Console, CLI.
|
||
- **Surfaces:** OpenAPI specs, language SDKs, developer portal, examples, mock server, conformance tests, changelog feeds, deprecation notices.
|
||
- **Dependencies:** Authority scopes/tenancy, CLI parity, Export Center, Notifications, Air-Gapped Mode, Observability.
|
||
|
||
## Program pillars
|
||
|
||
1. **Contract-first:** treat OpenAPI specs as the source of truth. CI validates schemas, compatibility, and documentation generation.
|
||
2. **SDK parity:** language SDKs cover the same surfaces with deterministic clients, pagination helpers, and typed models mirroring Aggregation-Only Contract semantics.
|
||
3. **Version discipline:** semantic versioning for specs and SDKs, release notes, deprecation windows, and automated change alerts via Notifications.
|
||
4. **Offline readiness:** specs and SDK bundles ship in Mirror Bundles for air-gapped environments; examples include smoke tests.
|
||
5. **Observability:** telemetry around SDK usage, spec download metrics, and error reporting funnels back into product decisions.
|
||
|
||
## Deliverables
|
||
|
||
| Workstream | Deliverable |
|
||
| --- | --- |
|
||
| Spec authoring | Unified OpenAPI 3.1 documents per service plus aggregate spec; lint rules; schema registries. |
|
||
| SDK generation | Language-specific clients with idiomatic ergonomics, retries, pagination, long-running operation helpers, unit + integration tests. |
|
||
| Dev portal | Consolidated documentation, guides, changelog, copy/paste examples, quickstart scripts. |
|
||
| Testing | Contract tests against staging, mock server for integration tests, compatibility verification per release. |
|
||
| Release ops | Automated CI pipelines, version bump workflows, release notes, deprecation policies. |
|
||
|
||
## Guardrails
|
||
|
||
- **Aggregation-Only Contract compliance:** SDKs expose raw advisory/VEX objects without hidden merges; all derived fields require explicit Policy Engine calls.
|
||
- **Security:** enforce scopes via SDK configuration; redact secrets; support DPoP/mTLS and offline token provisioning.
|
||
- **Compatibility:** maintain backwards-compatible paths for at least two minor releases; log warnings on deprecated endpoints.
|
||
- **Documentation:** publish examples for common workflows (scan, policy evaluate, export, attestation) with language parity.
|
||
|
||
## Roadmap checkpoints
|
||
|
||
1. Baseline OpenAPI specs extracted from gateway, validated, and published.
|
||
2. TypeScript/Node SDK as pilot, followed by Python and Go.
|
||
3. Developer portal launch with SDK docs, quickstarts, and mock server.
|
||
4. Offline kit integration (mirror bundles include specs + SDK tarballs).
|
||
5. Runtime alerting for breaking changes and dependency vulnerabilities.
|
||
|
||
## References
|
||
|
||
- API gateway integration: `docs/modules/platform/architecture-overview.md`
|
||
- Policy/Findings models: `docs/modules/policy/architecture.md`, `docs/modules/vuln-explorer/architecture.md`
|
||
- Export bundle distribution: `docs/modules/export-center/overview.md`
|
||
- Offline workflows: `docs/airgap/airgap-mode.md`
|