up

docs/api/overview.md

@@ -0,0 +1,54 @@
+# 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.