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, Excitor, 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
- Contract-first: treat OpenAPI specs as the source of truth. CI validates schemas, compatibility, and documentation generation.
- SDK parity: language SDKs cover the same surfaces with deterministic clients, pagination helpers, and typed models mirroring Aggregation-Only Contract semantics.
- Version discipline: semantic versioning for specs and SDKs, release notes, deprecation windows, and automated change alerts via Notifications.
- Offline readiness: specs and SDK bundles ship in Mirror Bundles for air-gapped environments; examples include smoke tests.
- 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
- Baseline OpenAPI specs extracted from gateway, validated, and published.
- TypeScript/Node SDK as pilot, followed by Python and Go.
- Developer portal launch with SDK docs, quickstarts, and mock server.
- Offline kit integration (mirror bundles include specs + SDK tarballs).
- 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