60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
# 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
|