query-orchestration/docs/ai.generated/03-api-documentation.md

API Documentation

API Overview

The DoczyAI Query Orchestration Platform exposes a comprehensive REST API following OpenAPI 3.0.3 specification. The API is automatically generated from the specification file serviceAPIs/queryAPI.yaml using oapi-codegen.

Base Configuration

• Base URL: https://doczy.com/v1 (production), http://localhost:8080 (development)
• API Version: 0.0.1
• Content Type: application/json
• Documentation: Auto-generated Swagger UI at /swagger/index.html

Authentication and Authorization

Security Schemes

JWT Authentication

• Type: Bearer token authentication
• Header: Authorization: Bearer <token>
• Token Source: JWT cookie set via OAuth flow

OAuth2 Flow

• Type: OAuth2 Authorization Code Flow
• Provider: AWS Cognito
• Scopes: Group-based permissions

Authentication Endpoints

GET /login

Initiates OAuth2 authentication flow with AWS Cognito.

Response: Redirect to Cognito login page

GET /login-callback

OAuth2 callback handler that processes authentication response.

Parameters:

• code (query): Authorization code from Cognito
• state (query): CSRF protection parameter

Response: Sets JWT cookie and redirects to dashboard

GET /logout

Terminates user session and clears authentication cookies.

Response: Redirect to login page

GET /home

Protected dashboard endpoint showing user information.

Security: Requires authentication Response: HTML dashboard page

Authorization Model

Permission Groups

• exporters: Can access export operations
• uploaders: Can upload documents and manage clients
• querybuilders: Can create and modify queries

Route Permissions

/client/*     → exporters, uploaders, querybuilders
/document/*   → exporters, querybuilders  
/query/*      → exporters, uploaders, querybuilders
/export/*     → exporters only
/health       → public (no authentication required)

Core API Endpoints

Client Management

POST /client

Creates a new client in the system.

Security: Requires uploaders or querybuilders permission

Request Body:

{
  "clientId": "string (max 256 chars)",
  "name": "string (max 256 chars)"
}

Responses:

• 201: Client created successfully
• 400: Invalid request data
• 401: Authentication required
• 403: Insufficient permissions

GET /client/{id}

Retrieves client details by ID.

Path Parameters:

• id: Client identifier (string, max 256 chars)

Response Example:

{
  "clientId": "acme-corp",
  "name": "ACME Corporation"
}

PATCH /client/{id}

Updates client information.

Request Body:

{
  "name": "string (max 256 chars)"
}

GET /client/{id}/status

Returns client synchronization status.

Response Example:

{
  "status": "IN_SYNC" | "NOT_SYNCED" | "NOT_SYNCING"
}

Document Operations

POST /client/{id}/document

Uploads a document for a specific client.

Content Type: multipart/form-data Max File Size: 100GB Supported Types: PDF (extensible)

Form Parameters:

• file: Document file (required)

Response:

{
  "documentId": "uuid",
  "clientId": "string",
  "filename": "string",
  "uploadedAt": "2024-01-01T00:00:00Z"
}

GET /client/{id}/document

Lists documents for a client with optional filtering.

Query Parameters:

• limit: Maximum results (integer)
• offset: Pagination offset (integer)

Response:

{
  "documents": [
    {
      "documentId": "uuid",
      "clientId": "string",
      "filename": "string",
      "status": "string",
      "uploadedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "total": "integer"
}

GET /document/{id}

Retrieves document metadata by ID.

Path Parameters:

• id: Document UUID

Query Management

GET /query

Lists all available queries in the system.

Response:

{
  "queries": [
    {
      "queryId": "uuid",
      "queryType": "JSON_EXTRACTOR" | "CONTEXT_FULL",
      "name": "string",
      "description": "string",
      "version": "integer"
    }
  ]
}

POST /query

Creates a new query definition.

Request Body:

{
  "queryType": "JSON_EXTRACTOR" | "CONTEXT_FULL",
  "name": "string (max 256 chars)",
  "description": "string (max 512 chars)",
  "config": "object (JSON configuration)"
}

GET /query/{id}

Retrieves query details including configuration.

PATCH /query/{id}

Updates query definition and increments version.

POST /query/{id}/test

Tests query execution against sample data.

Request Body:

{
  "testData": "string",
  "documentId": "uuid (optional)"
}

Collector Configuration

GET /client/{id}/collector

Retrieves collector configuration for a client.

Response:

{
  "clientId": "string",
  "queries": [
    {
      "name": "string",
      "queryId": "uuid"
    }
  ],
  "minCleanVersion": "integer",
  "minTextVersion": "integer"
}

PATCH /client/{id}/collector

Updates collector configuration.

Export Operations

POST /client/{id}/export

Triggers data export for a client.

Request Body:

{
  "format": "CSV" | "JSON" | "EXCEL",
  "filters": {
    "queryIds": ["uuid"],
    "dateRange": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-12-31T23:59:59Z"
    }
  }
}

GET /export/{id}

Checks export status and retrieves download URL.

Response:

{
  "exportId": "uuid",
  "status": "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED",
  "downloadUrl": "string (when completed)",
  "createdAt": "2024-01-01T00:00:00Z",
  "completedAt": "2024-01-01T00:05:00Z"
}

Request/Response Schemas

Standard Response Headers

All API responses include:

• RateLimit: Current rate limit status (format: 100;window=60)
• Content-Type: application/json (except file downloads)

Error Response Format

{
  "message": "Error description (max 256 chars)"
}

Common HTTP Status Codes

• 200: Success
• 201: Created
• 400: Bad Request (validation errors)
• 401: Unauthorized (authentication required)
• 403: Forbidden (insufficient permissions)
• 404: Not Found
• 429: Too Many Requests (rate limited)
• 500: Internal Server Error

Rate Limiting

Current Limits

• Rate: 100 requests per 60-second window
• Scope: Per authenticated user
• Headers: RateLimit header shows current status
• Exceeded: Returns 429 with Retry-After header

API Versioning

Current Strategy

• URL-based versioning: /v1 prefix
• Backward Compatibility: Maintained within major versions
• OpenAPI Version: 0.0.1 (development phase)

Future Considerations

• Semantic versioning for production releases
• Deprecation notices for breaking changes
• Version sunset policies

Code Generation

OpenAPI Integration

The API is generated from the OpenAPI specification using:

oapi-codegen -generate "types,server" -o api.gen.go serviceAPIs/queryAPI.yaml

Generated Artifacts

• Type-safe Go structs for requests/responses
• Echo framework route handlers
• OpenAPI validation middleware
• Swagger documentation

Validation

• Automatic request validation against OpenAPI schema
• Response validation in development mode
• Parameter binding with type safety