Basis of an OpenAPI spec

specs/api/README.md

@@ -0,0 +1,84 @@
+# TrustGraph OpenAPI Specification
+
+This directory contains the modular OpenAPI 3.1 specification for the TrustGraph REST API Gateway.
+
+## 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)

specs/api/components/parameters/Collection.yaml

@@ -0,0 +1,8 @@
+name: collection
+in: query
+required: false
+schema:
+  type: string
+  default: default
+description: Collection identifier
+example: default

specs/api/components/parameters/FlowId.yaml

@@ -0,0 +1,7 @@
+name: flow
+in: path
+required: true
+schema:
+  type: string
+description: Flow instance ID
+example: my-flow

specs/api/components/parameters/User.yaml

@@ -0,0 +1,8 @@
+name: user
+in: query
+required: false
+schema:
+  type: string
+  default: trustgraph
+description: User identifier
+example: alice

specs/api/components/responses/Error.yaml

@@ -0,0 +1,23 @@
+description: Error response
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        error:
+          oneOf:
+            - type: string
+              description: Simple error message
+            - $ref: '../schemas/errors/ErrorObject.yaml'
+              description: Structured error with type and message
+    examples:
+      simpleError:
+        summary: Simple error message
+        value:
+          error: Invalid flow ID
+      structuredError:
+        summary: Structured error
+        value:
+          error:
+            type: gateway-error
+            message: Timeout

specs/api/components/responses/Unauthorized.yaml

@@ -0,0 +1,9 @@
+description: Unauthorized - Invalid or missing bearer token
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        error:
+          type: string
+          example: Unauthorized

specs/api/components/schemas/common/DocumentMetadata.yaml

@@ -0,0 +1,26 @@
+type: object
+description: Document metadata for library management
+properties:
+  url:
+    type: string
+    description: Document URL or identifier
+    example: https://example.com/document.pdf
+  title:
+    type: string
+    description: Document title
+    example: Example Document
+  author:
+    type: string
+    description: Document author
+    example: John Doe
+  date:
+    type: string
+    description: Document date
+    example: "2024-01-15"
+  metadata:
+    type: object
+    description: Additional metadata fields
+    additionalProperties: true
+    example:
+      department: Engineering
+      category: Technical

specs/api/components/schemas/common/ProcessingMetadata.yaml

@@ -0,0 +1,25 @@
+type: object
+description: Processing metadata for library document processing
+properties:
+  flow:
+    type: string
+    description: Flow ID
+    example: my-flow
+  collection:
+    type: string
+    description: Collection identifier
+    example: default
+  status:
+    type: string
+    description: Processing status
+    enum: [pending, processing, completed, failed]
+    example: completed
+  timestamp:
+    type: string
+    format: date-time
+    description: Processing timestamp
+    example: "2024-01-15T10:30:00Z"
+  error:
+    type: string
+    description: Error message if processing failed
+    example: Failed to extract text from PDF

specs/api/components/schemas/common/RdfValue.yaml

@@ -0,0 +1,21 @@
+type: object
+description: |
+  RDF value - represents either a URI/entity or a literal value.
+
+  When `e` is true, `v` must be a full URI (e.g., http://schema.org/name).
+  When `e` is false, `v` is a literal value (string, number, etc.).
+properties:
+  v:
+    type: string
+    description: The value - full URI when e=true, literal when e=false
+    example: http://example.com/Person1
+  e:
+    type: boolean
+    description: True if entity/URI, false if literal value
+    example: true
+required:
+  - v
+  - e
+example:
+  v: http://schema.org/name
+  e: true

specs/api/components/schemas/common/Triple.yaml

@@ -0,0 +1,29 @@
+type: object
+description: |
+  RDF triple representing a subject-predicate-object statement in the knowledge graph.
+
+  Example: (Person1) -[has name]-> ("John Doe")
+properties:
+  s:
+    $ref: './RdfValue.yaml'
+    description: Subject - the entity the statement is about
+  p:
+    $ref: './RdfValue.yaml'
+    description: Predicate - the property or relationship
+  o:
+    $ref: './RdfValue.yaml'
+    description: Object - the value or target entity
+required:
+  - s
+  - p
+  - o
+example:
+  s:
+    v: http://example.com/Person1
+    e: true
+  p:
+    v: http://schema.org/name
+    e: true
+  o:
+    v: John Doe
+    e: false

specs/api/components/schemas/errors/ErrorObject.yaml

@@ -0,0 +1,14 @@
+type: object
+description: Structured error response with type and message
+properties:
+  type:
+    type: string
+    description: Error type identifier
+    example: gateway-error
+  message:
+    type: string
+    description: Human-readable error message
+    example: Timeout
+required:
+  - type
+  - message

specs/api/openapi.yaml

@@ -0,0 +1,129 @@
+openapi: 3.1.0
+
+info:
+  title: TrustGraph API Gateway
+  version: 1.8.0
+  description: |
+    REST API for TrustGraph - an AI-powered knowledge graph and RAG system.
+
+    ## Overview
+
+    The API provides access to:
+    - **Global Services**: Configuration, flow management, knowledge storage, library management
+    - **Flow-Hosted Services**: AI services like RAG, text completion, embeddings (require running flow)
+    - **Import/Export**: Bulk data operations for triples, embeddings, entity contexts
+    - **WebSocket**: Multiplexed interface for all services
+
+    ## Service Types
+
+    ### Global Services
+    Fixed endpoints accessible via `/api/v1/{kind}`:
+    - `config` - Configuration management
+    - `flow` - Flow lifecycle and blueprints
+    - `librarian` - Document library management
+    - `knowledge` - Knowledge graph core management
+    - `collection-management` - Collection metadata
+
+    ### Flow-Hosted Services
+    Require running flow instance, accessed via `/api/v1/flow/{flow}/service/{kind}`:
+    - AI services: agent, text-completion, prompt, RAG (document/graph)
+    - Embeddings: embeddings, graph-embeddings, document-embeddings
+    - Query: triples, objects, nlp-query, structured-query
+    - Data loading: text-load, document-load
+    - Utilities: mcp-tool, structured-diag
+
+    ## Authentication
+
+    Bearer token authentication when `GATEWAY_SECRET` environment variable is set.
+    Include token in Authorization header:
+    ```
+    Authorization: Bearer <token>
+    ```
+
+    If `GATEWAY_SECRET` is not set, API runs without authentication (development mode).
+
+    ## Field Naming
+
+    All JSON fields use **kebab-case**: `flow-id`, `blueprint-name`, `doc-limit`, etc.
+
+    ## Error Responses
+
+    All endpoints may return errors in this format:
+    ```json
+    {
+      "error": {
+        "type": "gateway-error",
+        "message": "Timeout"
+      }
+    }
+    ```
+
+  contact:
+    name: TrustGraph Project
+    url: https://trustgraph.ai
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+
+servers:
+  - url: http://localhost:8088
+    description: Local development server
+  - url: http://localhost:8088/api/v1
+    description: API v1 base path
+
+security:
+  - bearerAuth: []
+
+tags:
+  - name: Config
+    description: Configuration management (global service)
+  - name: Flow
+    description: Flow lifecycle and blueprint management (global service)
+  - name: Librarian
+    description: Document library management (global service)
+  - name: Knowledge
+    description: Knowledge graph core management (global service)
+  - name: Collection
+    description: Collection metadata management (global service)
+  - name: AI Services
+    description: AI services hosted within flows
+  - name: Import/Export
+    description: Bulk data import and export
+  - name: WebSocket
+    description: WebSocket interfaces
+  - name: Metrics
+    description: System metrics and monitoring
+
+paths:
+  # Global services will be added here as we build them
+  # /api/v1/config:
+  #   $ref: './paths/config.yaml'
+  # /api/v1/flow:
+  #   $ref: './paths/flow.yaml'
+  # etc.
+
+components:
+  securitySchemes:
+    bearerAuth:
+      $ref: './security/bearerAuth.yaml'
+
+  parameters:
+    # Common parameters will be referenced here
+    # FlowId:
+    #   $ref: './components/parameters/FlowId.yaml'
+
+  responses:
+    # Common responses will be referenced here
+    # Unauthorized:
+    #   $ref: './components/responses/Unauthorized.yaml'
+    # Error:
+    #   $ref: './components/responses/Error.yaml'
+
+  schemas:
+    # Schemas will be referenced here as we build them
+    # Common:
+    #   RdfValue:
+    #     $ref: './components/schemas/common/RdfValue.yaml'
+    # Services:
+    #   ConfigRequest:
+    #     $ref: './components/schemas/config/ConfigRequest.yaml'

specs/api/security/bearerAuth.yaml

@@ -0,0 +1,12 @@
+type: http
+scheme: bearer
+description: |
+  Bearer token authentication.
+
+  Set via `GATEWAY_SECRET` environment variable on the gateway.
+  If `GATEWAY_SECRET` is not set, authentication is disabled (development mode).
+
+  Example:
+  ```
+  Authorization: Bearer your-secret-token
+  ```