9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Signals CI & Image / signals-ci (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
55 lines
2.6 KiB
Markdown
55 lines
2.6 KiB
Markdown
# StellaOps API Overview
|
|
|
|
Last updated: 2025-11-25 (Md.V docs stream)
|
|
|
|
## Scope
|
|
Shared conventions for all StellaOps HTTP APIs. Service-specific schemas live under `src/Api/StellaOps.Api.OpenApi` and composed `out/api/stella.yaml`.
|
|
|
|
## Authentication & tenancy
|
|
- **Auth**: Bearer tokens (`Authorization: Bearer <token>`); service accounts must include `aud` for the target service.
|
|
- **Tenancy**: Multi-tenant endpoints require `X-Stella-Tenant` (or embedded tenant in token claims). Requests without tenant fail with `403` + `error.code = TENANT_REQUIRED`.
|
|
- **Scopes**: Each endpoint documents required scopes; clients must send least-privilege tokens.
|
|
|
|
## Pagination
|
|
- Cursor-based: `page_token` (opaque), `page_size` (default 50, max 500 unless noted).
|
|
- Responses include `next_page_token` when more results are available.
|
|
- Ordering is deterministic per endpoint (documented under each path).
|
|
|
|
## Idempotency
|
|
- Write endpoints accept optional `Idempotency-Key` header (UUID). Servers must de-duplicate on key + tenant + path.
|
|
- Idempotent methods: GET/HEAD/OPTIONS always; POST/PUT/PATCH/DELETE idempotent only when key is provided and documented.
|
|
|
|
## Rate limits
|
|
- Standard headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (UTC epoch seconds).
|
|
- 429 responses use the standard error envelope; clients should back off using `Retry-After` when present.
|
|
|
|
## Error envelope
|
|
All error responses use:
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "STRING_ENUM",
|
|
"message": "human readable",
|
|
"trace_id": "<trace or correlation id>"
|
|
}
|
|
}
|
|
```
|
|
- `trace_id` maps to server traces/logs; CLI/Console surface it in verbose output.
|
|
|
|
## Headers
|
|
- Required observability headers: `traceparent` (W3C), optional `baggage` for routing; services echo correlation IDs in responses.
|
|
- Content negotiation: `Accept` defaults to `application/json`; NDJSON endpoints use `application/x-ndjson`.
|
|
- All times are UTC ISO-8601; hashes are lowercase hex.
|
|
|
|
## Determinism & offline
|
|
- APIs must return stable ordering for identical inputs; list endpoints document their sort keys.
|
|
- Clients should operate offline using cached responses where supported; air-gap endpoints document required bundles/trust roots.
|
|
|
|
## Checklist for new/changed endpoints
|
|
- [ ] Added request/response examples (see `examples/` folders).
|
|
- [ ] Spectral lint passes (`pnpm api:lint`).
|
|
- [ ] Compat report reviewed (`pnpm api:compat` vs `stella-baseline.yaml`).
|
|
- [ ] Changelog artefacts generated (`out/api/changelog/*` with checksums/signature).
|
|
- [ ] Error envelope and headers documented.
|
|
- [ ] Pagination, idempotency, tenancy, scopes documented.
|