48702191be
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
feat(sbomservice): Add placeholder for SHA256SUMS in LNM v1 fixtures docs(devportal): Create README for SDK archives in public directory build(devportal): Implement offline bundle build script test(devportal): Add link checker script for validating links in documentation test(devportal): Create performance check script for dist folder size test(devportal): Implement accessibility check script using Playwright and Axe docs(devportal): Add SDK quickstart guide with examples for Node.js, Python, and cURL feat(excititor): Implement MongoDB storage for airgap import records test(findings): Add unit tests for export filters hash determinism feat(findings): Define attestation contracts for ledger web service feat(graph): Add MongoDB options and service collection extensions for graph indexing test(graph): Implement integration tests for MongoDB provider and service collection extensions feat(zastava): Define configuration options for Zastava surface secrets build(tests): Create script to run Concelier linkset tests with TRX output
488 lines
15 KiB
YAML
488 lines
15 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: StellaOps Graph Gateway (draft)
|
|
version: 0.0.2-pre
|
|
description: |
|
|
Draft API surface for graph search/query/paths/diff/export with streaming tiles,
|
|
cost budgets, overlays, and RBAC headers. Aligns with sprint 0207 Wave 1 outline
|
|
(GRAPH-API-28-001..011).
|
|
servers:
|
|
- url: https://gateway.local/api
|
|
security:
|
|
- bearerAuth: []
|
|
|
|
paths:
|
|
/graph/search:
|
|
post:
|
|
summary: Search graph nodes with prefix/exact semantics and filters
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SearchRequest'
|
|
responses:
|
|
'200':
|
|
description: Stream of search tiles (NDJSON)
|
|
content:
|
|
application/x-ndjson:
|
|
schema:
|
|
$ref: '#/components/schemas/TileEnvelope'
|
|
examples:
|
|
sample:
|
|
summary: Node + cursor tiles
|
|
value: |
|
|
{"type":"node","seq":0,"data":{"id":"gn:tenant:component:abc","kind":"component","tenant":"acme","attributes":{"purl":"pkg:npm/lodash@4.17.21"}},"cost":{"limit":1000,"remaining":999,"consumed":1}}
|
|
{"type":"cursor","seq":1,"data":{"token":"cursor-123","resumeUrl":"https://gateway.local/api/graph/query?cursor=cursor-123"}}
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
'429': { $ref: '#/components/responses/BudgetExceeded' }
|
|
|
|
/graph/query:
|
|
post:
|
|
summary: Execute graph query with budgeted streaming tiles
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryRequest'
|
|
responses:
|
|
'200':
|
|
description: Stream of query tiles (NDJSON)
|
|
content:
|
|
application/x-ndjson:
|
|
schema:
|
|
$ref: '#/components/schemas/TileEnvelope'
|
|
examples:
|
|
mixedTiles:
|
|
summary: Node + edge + stats tiles
|
|
value: |
|
|
{"type":"node","seq":0,"data":{"id":"gn:tenant:artifact:sha256:...","tenant":"acme","kind":"artifact","attributes":{"sbom_digest":"sha256:abc"}}}
|
|
{"type":"edge","seq":1,"data":{"id":"ge:tenant:CONTAINS:...","sourceId":"gn:tenant:artifact:...","targetId":"gn:tenant:component:...","kind":"CONTAINS"}}
|
|
{"type":"stats","seq":2,"data":{"nodesEmitted":1,"edgesEmitted":1,"depthReached":2,"cacheHitRatio":0.8}}
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
'429': { $ref: '#/components/responses/BudgetExceeded' }
|
|
|
|
/graph/paths:
|
|
post:
|
|
summary: Find constrained paths between node sets (depth ≤ 6)
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PathsRequest'
|
|
responses:
|
|
'200':
|
|
description: Stream of path tiles ordered by hop
|
|
content:
|
|
application/x-ndjson:
|
|
schema:
|
|
$ref: '#/components/schemas/TileEnvelope'
|
|
examples:
|
|
pathTiles:
|
|
summary: Path tiles grouped by hop
|
|
value: |
|
|
{"type":"node","seq":0,"data":{"id":"gn:tenant:component:src","kind":"component","tenant":"acme"}}
|
|
{"type":"edge","seq":1,"data":{"id":"ge:tenant:DEPENDS_ON:1","sourceId":"gn:tenant:component:src","targetId":"gn:tenant:component:dst","kind":"DEPENDS_ON"}}
|
|
{"type":"stats","seq":2,"data":{"nodesEmitted":2,"edgesEmitted":1,"depthReached":1}}
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
'429': { $ref: '#/components/responses/BudgetExceeded' }
|
|
|
|
/graph/diff:
|
|
post:
|
|
summary: Stream diff between two graph snapshots with overlay deltas
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DiffRequest'
|
|
responses:
|
|
'200':
|
|
description: Stream of diff tiles (added/removed/changed)
|
|
content:
|
|
application/x-ndjson:
|
|
schema:
|
|
$ref: '#/components/schemas/TileEnvelope'
|
|
examples:
|
|
diffTiles:
|
|
summary: Added/removed tiles
|
|
value: |
|
|
{"type":"node","seq":0,"data":{"id":"gn:tenant:component:new","kind":"component","tenant":"acme","attributes":{"purl":"pkg:npm/new@1.0.0"}}}
|
|
{"type":"diagnostic","seq":1,"data":{"level":"info","message":"snapshot diff complete"}}
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
|
|
/graph/export/{jobId}/manifest:
|
|
get:
|
|
summary: Download deterministic checksum manifest for a completed export job
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
- name: jobId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Deterministic manifest
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
files:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
path: { type: string }
|
|
sha256: { type: string }
|
|
size: { type: integer }
|
|
exportId: { type: string }
|
|
'404': { description: Manifest not ready or job missing }
|
|
|
|
/graph/export:
|
|
post:
|
|
summary: Request export job for snapshot or query result
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ExportRequest'
|
|
responses:
|
|
'202':
|
|
description: Export job accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ExportJob'
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
|
|
/graph/export/{jobId}:
|
|
get:
|
|
summary: Check export job status or download manifest
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
- name: jobId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Job status
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ExportJob'
|
|
'404':
|
|
description: Job not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
|
|
parameters:
|
|
TenantHeader:
|
|
name: X-Stella-Tenant
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Tenant identifier enforced on all routes.
|
|
RequestIdHeader:
|
|
name: X-Request-Id
|
|
in: header
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Optional caller-provided correlation id, echoed in responses.
|
|
|
|
schemas:
|
|
CostBudget:
|
|
type: object
|
|
properties:
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
example: 1000
|
|
remaining:
|
|
type: integer
|
|
minimum: 0
|
|
example: 995
|
|
consumed:
|
|
type: integer
|
|
minimum: 0
|
|
example: 5
|
|
required: [limit, remaining, consumed]
|
|
|
|
TileEnvelope:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [node, edge, stats, cursor, diagnostic]
|
|
seq:
|
|
type: integer
|
|
minimum: 0
|
|
example: 0
|
|
cost:
|
|
$ref: '#/components/schemas/CostBudget'
|
|
data:
|
|
description: Payload varies by tile type.
|
|
oneOf:
|
|
- $ref: '#/components/schemas/NodeTile'
|
|
- $ref: '#/components/schemas/EdgeTile'
|
|
- $ref: '#/components/schemas/StatsTile'
|
|
- $ref: '#/components/schemas/CursorTile'
|
|
- $ref: '#/components/schemas/DiagnosticTile'
|
|
required: [type, seq]
|
|
|
|
NodeTile:
|
|
type: object
|
|
properties:
|
|
id: { type: string }
|
|
kind: { type: string }
|
|
tenant: { type: string }
|
|
attributes: { type: object }
|
|
overlays:
|
|
type: object
|
|
description: Optional overlay payloads (policy/vex/advisory) keyed by overlay kind.
|
|
required: [id, kind, tenant]
|
|
|
|
EdgeTile:
|
|
type: object
|
|
properties:
|
|
id: { type: string }
|
|
kind: { type: string }
|
|
sourceId: { type: string }
|
|
targetId: { type: string }
|
|
tenant: { type: string }
|
|
attributes: { type: object }
|
|
overlays:
|
|
type: object
|
|
required: [id, kind, sourceId, targetId, tenant]
|
|
|
|
StatsTile:
|
|
type: object
|
|
properties:
|
|
nodesEmitted: { type: integer, minimum: 0 }
|
|
edgesEmitted: { type: integer, minimum: 0 }
|
|
depthReached: { type: integer, minimum: 0 }
|
|
cacheHitRatio: { type: number, minimum: 0, maximum: 1 }
|
|
required: [nodesEmitted, edgesEmitted]
|
|
|
|
CursorTile:
|
|
type: object
|
|
properties:
|
|
token: { type: string }
|
|
resumeUrl: { type: string, format: uri }
|
|
required: [token]
|
|
|
|
DiagnosticTile:
|
|
type: object
|
|
properties:
|
|
level: { type: string, enum: [info, warn, error] }
|
|
message: { type: string }
|
|
details: { type: object }
|
|
required: [level, message]
|
|
|
|
SearchRequest:
|
|
type: object
|
|
properties:
|
|
query:
|
|
type: string
|
|
description: Prefix or exact text; required unless filters present.
|
|
kinds:
|
|
type: array
|
|
items:
|
|
type: string
|
|
limit:
|
|
type: integer
|
|
default: 50
|
|
maximum: 500
|
|
filters:
|
|
type: object
|
|
additionalProperties: true
|
|
ordering:
|
|
type: string
|
|
enum: [relevance, id]
|
|
required: [kinds]
|
|
|
|
QueryRequest:
|
|
type: object
|
|
properties:
|
|
dsl:
|
|
type: string
|
|
description: DSL expression for graph traversal (mutually exclusive with filter).
|
|
filter:
|
|
type: object
|
|
description: Structured filter alternative to DSL.
|
|
budget:
|
|
type: object
|
|
properties:
|
|
nodeCap: { type: integer }
|
|
edgeCap: { type: integer }
|
|
timeMs: { type: integer }
|
|
overlays:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum: [policy, vex, advisory]
|
|
explain:
|
|
type: string
|
|
enum: [none, minimal, full]
|
|
default: none
|
|
anyOf:
|
|
- required: [dsl]
|
|
- required: [filter]
|
|
|
|
PathsRequest:
|
|
type: object
|
|
properties:
|
|
sourceIds:
|
|
type: array
|
|
items: { type: string }
|
|
minItems: 1
|
|
targetIds:
|
|
type: array
|
|
items: { type: string }
|
|
minItems: 1
|
|
maxDepth:
|
|
type: integer
|
|
maximum: 6
|
|
default: 4
|
|
constraints:
|
|
type: object
|
|
properties:
|
|
edgeKinds:
|
|
type: array
|
|
items: { type: string }
|
|
fanoutCap:
|
|
type: integer
|
|
overlays:
|
|
type: array
|
|
items: { type: string }
|
|
required: [sourceIds, targetIds]
|
|
|
|
DiffRequest:
|
|
type: object
|
|
properties:
|
|
snapshotA: { type: string }
|
|
snapshotB: { type: string }
|
|
filters:
|
|
type: object
|
|
additionalProperties: true
|
|
required: [snapshotA, snapshotB]
|
|
|
|
ExportRequest:
|
|
type: object
|
|
properties:
|
|
snapshotId:
|
|
type: string
|
|
queryRef:
|
|
type: string
|
|
formats:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum: [graphml, csv, ndjson, png, svg]
|
|
includeOverlays:
|
|
type: boolean
|
|
default: false
|
|
anyOf:
|
|
- required: [snapshotId]
|
|
- required: [queryRef]
|
|
required: [formats]
|
|
|
|
ExportJob:
|
|
type: object
|
|
properties:
|
|
jobId: { type: string }
|
|
status: { type: string, enum: [pending, running, succeeded, failed] }
|
|
checksumManifestUrl: { type: string, format: uri }
|
|
downloadUrl: { type: string, format: uri }
|
|
createdAt: { type: string, format: date-time }
|
|
updatedAt: { type: string, format: date-time }
|
|
message: { type: string }
|
|
required: [jobId, status]
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
enum: [GRAPH_BUDGET_EXCEEDED, GRAPH_VALIDATION_FAILED, GRAPH_RATE_LIMITED, GRAPH_UNAUTHORIZED]
|
|
message:
|
|
type: string
|
|
details:
|
|
type: object
|
|
request_id:
|
|
type: string
|
|
required: [error, message]
|
|
|
|
responses:
|
|
ValidationError:
|
|
description: Request failed validation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
Unauthorized:
|
|
description: Missing or invalid credentials
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
BudgetExceeded:
|
|
description: Budget exhausted mid-stream; includes partial cursor details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|