stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
e5629454cf1e61cb6beb94e72d1f0bae8027b9aa
git.stella-ops.org/docs/api/sdk-openapi-program.md
master 8da4e12a90 Align AOC tasks for Excititor and Concelier
2025-10-31 18:50:15 +02:00

3.5 KiB
Raw Blame History

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