Developer APIs contracted
API documentation starts from committed contracts. This portal should render or link generated references, but it should not hand-edit endpoint or event shapes.
Reference Areas
- REST API from
doc/api/openapi.draft.yaml. - Events from
doc/api/asyncapi.draft.yaml. - Human, service-account, and future API-key access expectations.
- Error response and error-code catalog.
- Idempotency and retry expectations.
- CLI, SDK, and generated client entry points.
- NATS streams and event-consumer catalog.
- App SDK evidence path for launch, connect, decommission, and runtime proof.
- Rendered reference and API playground decisions that preserve contract-first source authority and keep try-it behavior security-reviewed.
Pages
- CLI Guide
- REST API
- Event API
- Event Streams
- AsyncAPI Rendering Path
- Auth And Access
- Idempotency And Retries
- Error Model
- Contract Artifacts
- REST Reference Pilot
- API Reference Rendering Options
- API Playground
- SDK Evidence Path
Implementation Note
The current portal syncs the committed OpenAPI and AsyncAPI YAML artifacts into the static site and exposes a REST reference pilot over those artifacts. API and event shapes stay generated or linked from the committed contracts; portal pages may explain reader intent, but they must not become hand-maintained endpoint or payload references.
| Reference area | Current portal behavior | Source authority |
|---|---|---|
| REST contract | Synced YAML artifact plus REST reference pilot | doc/api/openapi.draft.yaml |
| Event contract | Synced AsyncAPI artifact plus event guide/rendering path | doc/api/asyncapi.draft.yaml |
| Renderer decision | Tooling options documented before dependency adoption | renderer research pages |
| Playground | Research and safety model only; no live try-it enabled | playground decision page |
See API Reference Rendering Options for the plugin/tooling evaluation criteria before adding a generated reference dependency.
Interactive API playground work is separate from rendered reference work. It must decide mock, dev, sandbox, UAT, or partner execution mode; token handling; request masking; and publication-track safety before live calls are enabled.