stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/risk/api.md
StellaOps Bot 6c1177a6ce
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
Enhance risk API documentation and error handling 
- 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.
2025-12-06 00:47:29 +02:00

2.7 KiB
Raw Permalink Blame History

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