docs consolidation
This commit is contained in:
StellaOps Bot
@@ -1,123 +1,59 @@
|
||||
# Graph API
|
||||
# Graph Gateway API (draft)
|
||||
|
||||
Status: Draft (2025-11-26) — aligns with Sprint 0207 Graph API implementation (in-memory seed; RBAC + budgets enforced).
|
||||
This document describes the Graph Gateway HTTP surface at a high level and points to the authoritative contracts.
|
||||
|
||||
Base URL: `<gateway>/api/graph` (examples use relative paths).
|
||||
## Authoritative contracts
|
||||
|
||||
## Common headers
|
||||
- `X-Stella-Tenant` (required)
|
||||
- `Authorization: Bearer <token>` (required)
|
||||
- `X-Stella-Scopes`: space/comma/semicolon separated scopes
|
||||
- `/graph/search`: `graph:read` or `graph:query`
|
||||
- `/graph/query|paths|diff`: `graph:query`
|
||||
- `/graph/export`: `graph:export`
|
||||
Content-Type for requests: `application/json`
|
||||
Streaming responses: `application/x-ndjson`
|
||||
- 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`
|
||||
|
||||
## POST /graph/search
|
||||
Returns NDJSON stream of tiles (`node`, optional `cursor`).
|
||||
## What the Graph Gateway is for
|
||||
|
||||
Body:
|
||||
```json
|
||||
{
|
||||
"kinds": ["component", "artifact"],
|
||||
"query": "pkg:npm/",
|
||||
"filters": { "ecosystem": "npm" },
|
||||
"limit": 50,
|
||||
"cursor": "opaque"
|
||||
}
|
||||
```
|
||||
Errors:
|
||||
- 400 `GRAPH_VALIDATION_FAILED` (missing kinds/query/filters)
|
||||
- 401 missing auth; 403 missing scopes
|
||||
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
|
||||
|
||||
## POST /graph/query
|
||||
Streams nodes, edges (optional), stats, cursor with cost metadata.
|
||||
## Tenancy and authentication
|
||||
|
||||
Body:
|
||||
```json
|
||||
{
|
||||
"kinds": ["component"],
|
||||
"query": "widget",
|
||||
"filters": { "tenant": "acme" },
|
||||
"includeEdges": true,
|
||||
"includeStats": true,
|
||||
"includeOverlays": true,
|
||||
"limit": 100,
|
||||
"cursor": "opaque",
|
||||
"budget": { "tiles": 6000, "nodes": 5000, "edges": 10000 }
|
||||
}
|
||||
```
|
||||
Error tile if edge budget exceeded: `{ "type":"error","data":{"error":"GRAPH_BUDGET_EXCEEDED",...}}`
|
||||
- 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).
|
||||
|
||||
## POST /graph/paths
|
||||
Finds paths up to depth 6 between sources/targets.
|
||||
## NDJSON tile streaming
|
||||
|
||||
Body:
|
||||
```json
|
||||
{
|
||||
"sources": ["gn:acme:component:one"],
|
||||
"targets": ["gn:acme:component:two"],
|
||||
"kinds": ["depends_on"],
|
||||
"maxDepth": 4,
|
||||
"includeOverlays": false,
|
||||
"budget": { "tiles": 2000, "nodes": 1500, "edges": 3000 }
|
||||
}
|
||||
```
|
||||
Response: NDJSON tiles (`node`, `edge`, `stats`, `cursor`).
|
||||
Graph endpoints stream `application/x-ndjson`, where each line is a `TileEnvelope`.
|
||||
|
||||
## POST /graph/diff
|
||||
Diff two snapshots.
|
||||
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`
|
||||
|
||||
Body:
|
||||
```json
|
||||
{
|
||||
"snapshotA": "snapA",
|
||||
"snapshotB": "snapB",
|
||||
"includeEdges": true,
|
||||
"includeStats": true,
|
||||
"budget": { "tiles": 2000 }
|
||||
}
|
||||
```
|
||||
Response tiles: `node`/`edge` with change types, `stats`, optional `cursor`.
|
||||
## Cursor and resume
|
||||
|
||||
## POST /graph/export
|
||||
Kicks off an in-memory export job and returns manifest.
|
||||
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.
|
||||
|
||||
Body:
|
||||
```json
|
||||
{
|
||||
"format": "ndjson", // ndjson|csv|graphml|png|svg
|
||||
"includeEdges": true,
|
||||
"snapshotId": "snapA", // optional
|
||||
"kinds": ["component"], // optional
|
||||
"query": "pkg:", // optional
|
||||
"filters": { "ecosystem": "npm" }
|
||||
}
|
||||
```
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"jobId": "job-123",
|
||||
"status": "completed",
|
||||
"format": "ndjson",
|
||||
"sha256": "...",
|
||||
"size": 1234,
|
||||
"downloadUrl": "/graph/export/job-123",
|
||||
"completedAt": "2025-11-26T00:00:00Z"
|
||||
}
|
||||
```
|
||||
Download: `GET /graph/export/{jobId}` (returns file, headers include `X-Content-SHA256`).
|
||||
## Budgets and rate limits
|
||||
|
||||
## Health
|
||||
`GET /healthz` → 200 when service is ready; no auth/scopes required.
|
||||
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`)
|
||||
|
||||
## Error envelope
|
||||
```json
|
||||
{ "error": "GRAPH_VALIDATION_FAILED", "message": "details", "requestId": "optional" }
|
||||
```
|
||||
## Overlays
|
||||
|
||||
## Notes
|
||||
- All timestamps UTC ISO-8601.
|
||||
- Ordering is deterministic; cursors are opaque base64 offsets.
|
||||
- Overlays use `policy.overlay.v1` and `openvex.v1` payloads. Budgeted tiles reserve room for cursors when `hasMore` is true.
|
||||
`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
|
||||
|
||||
Reference in New Issue
Block a user