mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-05-30 01:35:14 +02:00
133 lines
3.8 KiB
Markdown
133 lines
3.8 KiB
Markdown
# TrustGraph OpenAPI Specification
|
|
|
|
This directory contains the modular OpenAPI 3.1 specification for the TrustGraph REST API Gateway.
|
|
|
|
## Authentication
|
|
|
|
Clients authenticate by passing an opaque bearer token in the
|
|
`Authorization` header. The gateway resolves the token to an
|
|
authenticated identity and an associated workspace. Tokens are
|
|
obtained via the IAM service (e.g. `tg-login` or `tg-create-api-key`).
|
|
|
|
## Service Tiers
|
|
|
|
API services are organized into three tiers based on their scoping:
|
|
|
|
### Global services
|
|
|
|
These services are not scoped to a workspace. They manage
|
|
system-wide resources.
|
|
|
|
- **IAM** — user management, authentication, API key lifecycle
|
|
|
|
### Workspace-scoped services
|
|
|
|
These services operate within the workspace associated with the
|
|
authenticated token. The workspace is resolved by the gateway from
|
|
the bearer token — it is not passed as an explicit parameter.
|
|
|
|
- **Config** — configuration management (prompts, token costs, etc.)
|
|
- **Librarian** — document library management
|
|
- **Knowledge** — knowledge graph core management
|
|
- **Collection Management** — collection metadata
|
|
- **Flow** — flow lifecycle and blueprint management
|
|
|
|
### Flow-scoped services
|
|
|
|
These services require a `flow` parameter identifying the processing
|
|
flow to use, in addition to the workspace context from the token.
|
|
|
|
- **Agent** — agentic AI interactions
|
|
- **Document RAG** — retrieval-augmented generation over documents
|
|
- **Graph RAG** — retrieval-augmented generation over knowledge graphs
|
|
- **Text Completion** — LLM text completion
|
|
- **Prompt** — prompt template expansion
|
|
- **Embeddings** — vector embedding generation
|
|
- **SPARQL Query** — SPARQL queries against the knowledge graph
|
|
- **Graph Embeddings** — knowledge graph embedding queries
|
|
- **Document Embeddings** — document embedding queries
|
|
- **Structured Query** — structured data queries
|
|
- **Row Embeddings** — structured data embedding queries
|
|
- **Rows Query** — row-level data queries
|
|
- **Triples Query** — knowledge graph triple queries
|
|
|
|
## Structure
|
|
|
|
```
|
|
specs/api/
|
|
├── openapi.yaml # Main entry point
|
|
├── paths/ # Endpoint definitions
|
|
│ ├── config.yaml
|
|
│ ├── flow.yaml
|
|
│ ├── flow-services/ # Flow-hosted services
|
|
│ └── import-export/
|
|
├── components/
|
|
│ ├── schemas/ # Request/response schemas
|
|
│ │ ├── config/
|
|
│ │ ├── flow/
|
|
│ │ ├── ai-services/
|
|
│ │ ├── common/
|
|
│ │ └── errors/
|
|
│ ├── parameters/ # Reusable parameters
|
|
│ ├── responses/ # Reusable responses
|
|
│ └── examples/ # Example payloads
|
|
└── security/ # Security schemes
|
|
└── bearerAuth.yaml
|
|
```
|
|
|
|
## Viewing the Spec
|
|
|
|
### Swagger UI
|
|
|
|
```bash
|
|
# Install swagger-ui
|
|
npm install -g swagger-ui-watcher
|
|
|
|
# View in browser
|
|
swagger-ui-watcher specs/api/openapi.yaml
|
|
```
|
|
|
|
### Redoc
|
|
|
|
```bash
|
|
# Install redoc-cli
|
|
npm install -g redoc-cli
|
|
|
|
# Generate static HTML
|
|
redoc-cli bundle specs/api/openapi.yaml -o api-docs.html
|
|
|
|
# View
|
|
open api-docs.html
|
|
```
|
|
|
|
### Online Validators
|
|
|
|
Upload `openapi.yaml` to:
|
|
- https://editor.swagger.io/
|
|
- https://redocly.com/redoc/
|
|
|
|
## Validation
|
|
|
|
```bash
|
|
# Install openapi-spec-validator
|
|
pip install openapi-spec-validator
|
|
|
|
# Validate
|
|
openapi-spec-validator specs/api/openapi.yaml
|
|
```
|
|
|
|
## Development
|
|
|
|
When adding a new service:
|
|
|
|
1. Create schema files in `components/schemas/{service}/`
|
|
2. Create path file in `paths/` or `paths/flow-services/`
|
|
3. Add examples if needed
|
|
4. Reference from `openapi.yaml`
|
|
5. Validate
|
|
|
|
## References
|
|
|
|
- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)
|
|
- [TrustGraph Tech Spec](../../docs/tech-specs/openapi-spec.md)
|
|
- [API Services Summary](../../API_SERVICES_SUMMARY.md)
|