Skip to main content

API Architecture

Public vs Internal Routes​

  • Public routes: authentication and tenant‑scoped APIs for alerts, agents, approvals, workflows, inventory, etc.
  • Internal routes (/internal/*): Cloud Tasks/Scheduler/Pub/Sub callbacks, protected by OIDC (INTERNAL_AUDIENCE).
  • API route handlers live under src/api/routes/ (e.g., agents.py, approvals.py, workflows.py, monitoring.py).

Design Guidelines​

  • Clear 2xx/4xx/5xx semantics; error responses with masked PII.
  • Idempotency for apply: change set step IDs and replay safety in ChangeSetExecutor.
  • Streaming support: optional live step events for long‑running remediations via WebSocket routes in websocket.py.
  • Full schema: API → REST API (OpenAPI).
  • Security architecture: Admin → Security.