cc69d332e3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implemented comprehensive unit tests for RabbitMqTransportServer, covering constructor, disposal, connection management, event handlers, and exception handling. - Added configuration tests for RabbitMqTransportServer to validate SSL, durable queues, auto-recovery, and custom virtual host options. - Created unit tests for UdpFrameProtocol, including frame parsing and serialization, header size validation, and round-trip data preservation. - Developed tests for UdpTransportClient, focusing on connection handling, event subscriptions, and exception scenarios. - Established tests for UdpTransportServer, ensuring proper start/stop behavior, connection state management, and event handling. - Included tests for UdpTransportOptions to verify default values and modification capabilities. - Enhanced service registration tests for Udp transport services in the dependency injection container.
61 lines
2.9 KiB
Markdown
61 lines
2.9 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`.
|
|
|
|
## Related Documentation
|
|
|
|
- [OpenAPI Discovery](openapi-discovery.md) - Discovery endpoints and aggregation
|
|
- [Schema Validation](../modules/router/schema-validation.md) - JSON Schema validation for microservice endpoints
|
|
- [OpenAPI Aggregation](../modules/router/openapi-aggregation.md) - Gateway OpenAPI document generation
|
|
|
|
## 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.
|