trustgraph/specs/README.md

TrustGraph API Specifications

This directory contains formal specifications for the TrustGraph API Gateway.

Directory Structure

specs/
├── api/              # OpenAPI 3.1.0 specification for REST API
│   ├── openapi.yaml  # Main entry point
│   ├── paths/        # Endpoint definitions
│   ├── components/   # Reusable schemas, responses, parameters
│   └── security/     # Security scheme definitions
│
├── websocket/        # AsyncAPI 3.0.0 specification for WebSocket API
│   ├── asyncapi.yaml # Main entry point
│   ├── channels/     # Channel definitions
│   ├── components/   # Message and schema definitions
│   └── STREAMING.md  # Streaming patterns documentation
│
└── README.md         # This file

Specifications

REST API (OpenAPI 3.1.0)

Location: specs/api/openapi.yaml

The REST API specification documents:

• 5 Global Services: config, flow, librarian, knowledge, collection-management
• 16 Flow-Hosted Services: agent, RAG, embeddings, queries, loading, tools
• Import/Export: Bulk data operations
• Metrics: Prometheus monitoring

Features:

• Modular structure with $ref to external files
• Comprehensive request/response schemas
• Authentication via Bearer tokens
• Field naming in kebab-case

WebSocket API (AsyncAPI 3.0.0)

Location: specs/websocket/asyncapi.yaml

The WebSocket API specification documents:

• Multiplexed async communication protocol
• Request/response message envelopes with ID correlation
• All services accessible via single WebSocket connection
• Streaming response patterns

Features:

• References REST API schemas (single source of truth)
• Message-based routing (service + optional flow parameters)
• Comprehensive streaming documentation
• Full async/multiplexing behavior

Building Documentation

Prerequisites

npm install -g @redocly/cli @asyncapi/cli

Or use npx (no installation required).

Generate REST API Documentation

Using Redocly (HTML):

cd specs/api
npx @redocly/cli build-docs openapi.yaml -o ../../docs/api.html

Preview in browser:

cd specs/api
npx @redocly/cli preview-docs openapi.yaml

Opens interactive documentation at http://localhost:8080

Validate:

cd specs/api
npx @redocly/cli lint openapi.yaml

Generate WebSocket API Documentation

Using AsyncAPI (HTML):

cd specs/websocket
npx -p @asyncapi/cli asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o /tmp/asyncapi-build -p singleFile=true --force-write
mv /tmp/asyncapi-build/index.html ../../docs/websocket.html
rm -rf /tmp/asyncapi-build

Notes:

• The generator must run from the specs/websocket directory to properly resolve relative $ref paths to OpenAPI schemas
• --use-new-generator flag enables generator v2 compatibility
• -p singleFile=true parameter generates a single standalone HTML file

Validate:

cd specs/websocket
npx @asyncapi/cli validate asyncapi.yaml

Build All Documentation

Use the provided build script:

./specs/build-docs.sh

This generates:

• docs/api.html - REST API documentation
• docs/websocket.html - WebSocket API documentation

Viewing Documentation

After building:

REST API:

xdg-open docs/api.html
# or
firefox docs/api.html

WebSocket API:

xdg-open docs/websocket.html
# or
firefox docs/websocket.html

Schema Reuse

The WebSocket API specification references the REST API schemas using relative paths:

# In specs/websocket/components/messages/requests/AgentRequest.yaml
request:
  $ref: '../../../../api/components/schemas/agent/AgentRequest.yaml'

This ensures:

• Single source of truth for all schemas
• Consistency between REST and WebSocket APIs
• Easy maintenance - update schemas in one place

Validation Status

Both specifications are validated and error-free:

• ✅ OpenAPI: Validated with Redocly CLI
• ✅ AsyncAPI: Validated with AsyncAPI CLI

Maintenance

Adding a New Service

1. Create schemas in specs/api/components/schemas/{service-name}/

   • {ServiceName}Request.yaml
   • {ServiceName}Response.yaml

2. Create path definition in specs/api/paths/ or specs/api/paths/flow/

3. Add path to main spec in specs/api/openapi.yaml

4. Create WebSocket message in specs/websocket/components/messages/requests/

   • Reference the OpenAPI request schema

5. Add to ServiceRequest message in specs/websocket/components/messages/ServiceRequest.yaml

6. Validate both specs:

   cd specs/api && npx @redocly/cli lint openapi.yaml
   cd specs/websocket && npx @asyncapi/cli validate asyncapi.yaml
   

Modifying an Existing Service

1. Update schema in specs/api/components/schemas/{service-name}/

2. Changes automatically apply to WebSocket spec via $ref

3. Validate both specs to ensure consistency

Tools and Resources

OpenAPI Tools:

• Redocly CLI - Linting, docs generation
• Swagger Editor - Online editor
• OpenAPI Generator - Client/server code generation

AsyncAPI Tools:

• AsyncAPI CLI - Validation, docs generation
• AsyncAPI Studio - Online editor
• AsyncAPI Generator - Template-based generation

Online Validators:

• OpenAPI: https://editor.swagger.io/
• AsyncAPI: https://studio.asyncapi.com/

API Version

Current version: 1.8.0

Version is specified in both:

• specs/api/openapi.yaml → info.version
• specs/websocket/asyncapi.yaml → info.version

Update both when releasing a new API version.