6c1177a6ce
- Updated API documentation for risk endpoints to include optional caching headers and error catalog references. - Added a new error catalog JSON file to standardize error responses. - Improved explainability documentation with sample outputs for console and CLI. - Added SHA256 checksums for new sample files related to explainability. - Refined AocGuard tests to utilize a helper method for generating test JSON, improving readability and maintainability. - Updated runbook references to ensure consistency in sprint documentation. - Introduced stub implementations for MongoDB storage interfaces and options, laying groundwork for future development. - Disabled analytics in Angular CLI configuration for privacy considerations.
46 lines
2.7 KiB
Markdown
46 lines
2.7 KiB
Markdown
# Risk API
|
|
|
|
> Based on `CONTRACT-RISK-SCORING-002` (2025-12-05). Examples are frozen in `docs/risk/samples/api/risk-api-samples.json` with hashes in `SHA256SUMS`. Keep ETags and error payloads deterministic.
|
|
|
|
## Purpose
|
|
- Document risk-related endpoints for profile management, simulation, scoring results, explainability retrieval, and export.
|
|
|
|
## Scope & Audience
|
|
- Audience: API consumers, SDK authors, platform integrators.
|
|
- In scope: endpoint list, methods, request/response schemas, auth/tenancy headers, rate limits, feature flags, error model.
|
|
- Out of scope: console/UI workflow details (see `explainability.md`).
|
|
|
|
## Endpoints (v1)
|
|
- `POST /api/v1/risk/jobs` — submit scoring job (body: job request); returns `202` with `job_id` and `status` (`queued`). Sample: `risk-api-samples.json#submit_job_request`.
|
|
- `GET /api/v1/risk/jobs/{job_id}` — job status + results array (sample: `get_job_status`).
|
|
- `GET /api/v1/risk/explain/{job_id}` — explainability payload (sample references `../explain/explain-trace.json`). Optional `If-None-Match` for caching.
|
|
- `GET /api/v1/risk/profiles` — list profiles (tenant-filtered); includes `profile_hash`, `version`, `etag` (see error-catalog headers).
|
|
- `POST /api/v1/risk/profiles` — create/update profile with DSSE/attestation metadata; returns `201` with `etag`.
|
|
- `POST /api/v1/risk/simulations` — dry-run scoring with fixtures; returns explain + contributions without persisting results.
|
|
- `GET /api/v1/risk/export/{job_id}` — export bundle (JSON + CSV + manifest) for auditors.
|
|
- Feature flags: `risk.jobs`, `risk.explain`, `risk.simulations`, `risk.export` (toggle exposure per tenant).
|
|
|
|
## Auth & Tenancy
|
|
- Required headers: `X-Stella-Tenant`, `Authorization: Bearer <token>`, optional `X-Stella-Scope` for imposed rule reminders.
|
|
- Imposed rule reminder must be present in responses where tenant-bound resources are returned.
|
|
|
|
## Error Model
|
|
- Envelope: `code`, `message`, `correlation_id`, `severity`, `remediation`; sample catalog in `docs/risk/samples/api/error-catalog.json`.
|
|
- Rate-limit headers: `Retry-After`, `X-RateLimit-Remaining`; caching headers include `ETag` for explain/results/profile GETs.
|
|
|
|
## Determinism & Offline Posture
|
|
- Samples: `docs/risk/samples/api/risk-api-samples.json` (hashes in `SHA256SUMS`); explain sample reused via relative reference.
|
|
- No live dependencies; use frozen fixtures. Keep ordering of fields stable in docs and samples.
|
|
|
|
## Open Items
|
|
- Add ETag examples for profile list/create once generators emit them.
|
|
- Populate error/code catalog and SDK targets once available.
|
|
- Align feature flag names with deployment config.
|
|
|
|
## References
|
|
- `docs/risk/overview.md`
|
|
- `docs/risk/profiles.md`
|
|
- `docs/risk/factors.md`
|
|
- `docs/risk/formulas.md`
|
|
- `docs/risk/explainability.md`
|