# 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