SDK & OpenAPI Program
This page describes how Stella Ops publishes and governs its public API contracts and client SDKs. It is written for platform engineers and integrators who consume the Stella Ops APIs, and for maintainers who evolve those contracts. For the day-to-day versioning and deprecation mechanics see API Versioning; for the shared request/response conventions see the API Overview.
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, Concelier, Excititor, 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 Overview — shared auth, tenancy, pagination, and idempotency conventions.
- API Versioning — semantic versioning, deprecation windows, and the spec/SDK release pipeline.
- Platform architecture overview — API gateway integration.
- Policy architecture and Findings Ledger architecture — Policy/Findings models.
- Export Center overview — export bundle distribution.
- Air-gapped mode guide — offline workflows.