# 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`