stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity

Enhance risk API documentation and error handling
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source 
- 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.
This commit is contained in:
StellaOps Bot
2025-12-06 00:47:29 +02:00
parent 582a88e8f8
commit 6c1177a6ce
19 changed files with 1403 additions and 1319 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/risk/api.md
View File

@@ -13,8 +13,8 @@
## 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`).
- `GET /api/v1/risk/profiles` — list profiles (tenant-filtered); include `profile_hash`, `version`, `etag`.
- `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.
@@ -25,8 +25,8 @@
- Imposed rule reminder must be present in responses where tenant-bound resources are returned.
## Error Model
- Envelope: `code`, `message`, `correlation_id`, `severity`, `remediation`.
- Rate-limit headers: `Retry-After`, `X-RateLimit-Remaining` (document values in SDKs).
- 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.