stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
4231305fec4a24de438f29dc639575a39fd3b469
git.stella-ops.org/docs/api/graph.md
StellaOps Bot 9a08d10b89 docs consolidation
2025-12-24 12:38:14 +02:00

2.5 KiB
Raw Blame History

Graph Gateway API (draft)

This document describes the Graph Gateway HTTP surface at a high level and points to the authoritative contracts.

Authoritative contracts

  • OpenAPI (endpoints, schemas, responses): docs/api/graph-gateway-spec-draft.yaml
  • Overlay + tile cache schema (materialized/cached representation): docs/api/graph/overlay-schema.md
  • Sample cached tile: docs/api/graph/samples/overlay-sample.json

What the Graph Gateway is for

Graph Gateway provides deterministic, tenant-scoped graph queries used for:

  • Impact analysis and traversal (search/query/paths/diff)
  • Overlay enrichment (policy, VEX, advisory) when requested
  • Export workflows for offline analysis and audit

Tenancy and authentication

  • Tenancy is mandatory for graph routes. The canonical tenant header name is deployment/profile dependent; see:
    • docs/api/gateway/tenant-auth.md
    • docs/modules/gateway/identity-header-policy.md
  • Authentication is typically Authorization: Bearer <token> with scopes per route.
    • Common scope families: graph:read, graph:query, graph:export (see OpenAPI for exact requirements).

NDJSON tile streaming

Graph endpoints stream application/x-ndjson, where each line is a TileEnvelope.

Key fields:

  • type: node, edge, stats, cursor, diagnostic
  • seq: monotonic integer per response stream
  • cost: optional per-stream budget counters (limit, remaining, consumed)
  • data: payload varies by type

Cursor and resume

When paging/resume is supported, responses can include a cursor tile with an opaque token. Requests can pass a cursor field to resume from a prior stream.

Budgets and rate limits

Budget/rate-limit enforcement is explicit and deterministic:

  • Responses may include headers such as X-RateLimit-Remaining and Retry-After
  • 429 responses use a stable error envelope (see OpenAPI components.responses)

Overlays

node and edge tiles may include overlays when requested. Overlays are keyed by overlay kind and carry {kind, version, data} so clients can render and cache without guessing schema.

For the cache/materialized representation used by gateway/UI tile caches, see docs/api/graph/overlay-schema.md.

Errors and determinism

  • Error shape follows platform conventions (see docs/api/overview.md), plus graph-specific error codes in the OpenAPI contract.
  • Determinism requirements:
    • stable ordering for equivalent requests
    • stable ids for nodes/edges where defined by schema
    • UTC ISO-8601 timestamps