DatomsDBS API 参考文档

版本: 1.0
基础URL: http://localhost:9000/api

认证 (Authentication)

获取访问令牌

端点: POST /auth/login

描述: 用户登录获取 JWT 访问令牌

请求体:

{
  "username": "admin",
  "password": "admin123"
}

成功响应 (200):

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "admin",
    "username": "admin",
    "roles": ["admin"]
  },
  "expiresIn": "24h"
}

错误响应 (401):

{
  "success": false,
  "error": "Invalid credentials"
}

令牌验证

端点: GET /auth/verify

请求头:

Authorization: Bearer <token>

成功响应 (200):

{
  "valid": true,
  "user": {
    "id": "admin",
    "username": "admin",
    "roles": ["admin"]
  }
}

数据源管理 API

获取数据源列表

端点: GET /data-sources

请求头:

Authorization: Bearer <token>

查询参数:

type (可选): 数据源类型过滤 (mysql, postgresql, mongodb, csv, etc.)
status (可选): 状态过滤 (active, inactive)
page (可选): 分页页码，默认 1
limit (可选): 每页数量，默认 20

成功响应 (200):

{
  "success": true,
  "data": [
    {
      "id": "ds_1234567890",
      "name": "用户数据库",
      "type": "mysql",
      "status": "active",
      "config": {
        "host": "localhost",
        "port": 3306,
        "database": "userdb"
      },
      "createdAt": "2024-12-28T10:00:00.000Z",
      "lastConnected": "2024-12-28T15:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "pages": 1
  }
}

创建数据源

端点: POST /data-sources

请求头:

Authorization: Bearer <token>
Content-Type: application/json

请求体 (MySQL 示例):

{
  "name": "生产用户数据库",
  "type": "mysql",
  "config": {
    "host": "mysql.example.com",
    "port": 3306,
    "database": "prod_users",
    "username": "readonly_user",
    "password": "secure_password",
    "ssl": true
  },
  "description": "生产环境用户数据",
  "tags": ["production", "users"]
}

请求体 (MongoDB 示例):

{
  "name": "日志数据库",
  "type": "mongodb",
  "config": {
    "uri": "mongodb://user:pass@cluster.mongodb.net/logs?retryWrites=true",
    "database": "application_logs",
    "collection": "error_logs"
  }
}

请求体 (CSV 文件示例):

{
  "name": "销售数据",
  "type": "csv",
  "config": {
    "filePath": "/data/uploads/sales_2024.csv",
    "delimiter": ",",
    "hasHeader": true,
    "encoding": "utf-8"
  }
}

成功响应 (201):

{
  "success": true,
  "data": {
    "id": "ds_1234567890",
    "name": "生产用户数据库",
    "type": "mysql",
    "status": "active",
    "createdAt": "2024-12-28T10:00:00.000Z"
  }
}

测试数据源连接

端点: POST /data-sources/{id}/test

请求头:

Authorization: Bearer <token>

成功响应 (200):

{
  "success": true,
  "message": "连接测试成功",
  "details": {
    "responseTime": 45,
    "recordCount": 1250,
    "schema": {
      "tables": ["users", "orders", "products"]
    }
  }
}

获取数据源数据预览

端点: GET /data-sources/{id}/preview

查询参数:

limit (可选): 预览记录数，默认 10，最大 100
table (可选): 指定表名 (关系型数据库)

成功响应 (200):

{
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "username": "john_doe",
        "email": "john@example.com",
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "schema": {
      "id": "integer",
      "username": "string",
      "email": "string",
      "created_at": "datetime"
    },
    "totalRecords": 1250,
    "previewCount": 10
  }
}

数据资产管理 API

获取数据资产列表

端点: GET /data-assets

查询参数:

category (可选): 分类过滤
owner (可选): 所有者过滤
search (可选): 搜索关键词
page, limit: 分页参数

成功响应 (200):

{
  "success": true,
  "data": [
    {
      "id": "asset_1234567890",
      "name": "用户行为分析数据集",
      "description": "包含用户登录、页面访问、购买行为等数据",
      "category": "analytics",
      "owner": "data_team",
      "sourceId": "ds_1234567890",
      "schema": {
        "user_id": "string",
        "event_type": "string",
        "timestamp": "instant",
        "properties": "object"
      },
      "recordCount": 50000,
      "size": "125MB",
      "createdAt": "2024-12-28T10:00:00.000Z",
      "lastUpdated": "2024-12-28T15:30:00.000Z",
      "tags": ["behavior", "analytics", "users"]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 25,
    "pages": 2
  }
}

创建数据资产

端点: POST /data-assets

请求体:

{
  "name": "客户订单分析",
  "description": "客户订单数据的聚合分析",
  "category": "business",
  "sourceId": "ds_1234567890",
  "extractConfig": {
    "query": "SELECT * FROM orders WHERE created_date >= '2024-01-01'",
    "incremental": true,
    "updateField": "updated_at"
  },
  "transformations": [
    {
      "type": "filter",
      "condition": "status = 'completed'"
    },
    {
      "type": "aggregate",
      "groupBy": ["customer_id"],
      "metrics": ["sum(amount)", "count(*)"]
    }
  ],
  "tags": ["orders", "customers", "revenue"]
}

成功响应 (201):

{
  "success": true,
  "data": {
    "id": "asset_9876543210",
    "name": "客户订单分析",
    "status": "processing",
    "estimatedCompletion": "2024-12-28T16:00:00.000Z"
  }
}

获取数据资产详情

端点: GET /data-assets/{id}

成功响应 (200):

{
  "success": true,
  "data": {
    "id": "asset_1234567890",
    "name": "用户行为分析数据集",
    "description": "包含用户登录、页面访问、购买行为等数据",
    "category": "analytics",
    "owner": "data_team",
    "sourceId": "ds_1234567890",
    "status": "ready",
    "schema": {
      "user_id": "string",
      "event_type": "string",
      "timestamp": "instant",
      "properties": "object"
    },
    "statistics": {
      "recordCount": 50000,
      "size": "125MB",
      "lastUpdated": "2024-12-28T15:30:00.000Z",
      "updateFrequency": "daily"
    },
    "access": {
      "public": false,
      "allowedRoles": ["analyst", "admin"],
      "allowedUsers": ["john.doe", "jane.smith"]
    },
    "lineage": {
      "upstream": ["ds_1234567890"],
      "downstream": ["dashboard_user_analytics"]
    }
  }
}

DatomsDB 操作 API

获取数据库列表

端点: GET /datoms/databases

成功响应 (200):

{
  "success": true,
  "databases": [
    {
      "name": "user_analytics",
      "created": "2024-12-28T10:00:00.000Z",
      "size": "50MB",
      "recordCount": 25000,
      "encrypted": false
    },
    {
      "name": "secure_finance",
      "created": "2024-12-27T14:30:00.000Z", 
      "size": "120MB",
      "recordCount": 75000,
      "encrypted": true
    }
  ]
}

创建数据库

端点: POST /datoms/databases

请求体:

{
  "name": "new_analytics_db",
  "schema": {
    "user_id": "string",
    "event": "string",
    "timestamp": "instant",
    "data": "object"
  },
  "options": {
    "encrypted": false,
    "autoSave": true,
    "saveInterval": 60000
  }
}

执行查询

端点: POST /datoms/databases/{dbName}/query

请求体 (Datalog 查询):

{
  "query": "[:find ?user ?event :where [?e :user_id ?user] [?e :event ?event]]",
  "inputs": {},
  "limit": 100
}

请求体 (简化查询):

{
  "entity": "user_events",
  "where": {
    "event": "login",
    "timestamp": {
      ">": "2024-12-28T00:00:00.000Z"
    }
  },
  "select": ["user_id", "timestamp", "ip_address"],
  "limit": 50,
  "orderBy": [{"field": "timestamp", "direction": "desc"}]
}

成功响应 (200):

{
  "success": true,
  "data": [
    ["user123", "login"],
    ["user456", "purchase"],
    ["user789", "logout"]
  ],
  "count": 3,
  "executionTime": 15
}

执行事务

端点: POST /datoms/databases/{dbName}/transact

请求体:

{
  "transaction": [
    {
      "op": "add",
      "entity": "user123",
      "attribute": "last_login",
      "value": "2024-12-28T16:00:00.000Z"
    },
    {
      "op": "add", 
      "entity": "user123",
      "attribute": "login_count",
      "value": 25
    }
  ]
}

成功响应 (200):

{
  "success": true,
  "transactionId": "tx_1234567890",
  "timestamp": "2024-12-28T16:00:00.000Z",
  "entitiesAffected": 1
}

用户与权限管理 API

获取用户列表

端点: GET /admin/users

权限要求: admin 角色

成功响应 (200):

{
  "success": true,
  "users": [
    {
      "id": "user_1",
      "username": "john.doe",
      "email": "john@example.com",
      "roles": ["analyst"],
      "active": true,
      "lastLogin": "2024-12-28T15:30:00.000Z",
      "createdAt": "2024-12-01T10:00:00.000Z"
    }
  ]
}

创建用户

端点: POST /admin/users

请求体:

{
  "username": "jane.smith",
  "email": "jane@example.com",
  "password": "SecurePassword123!",
  "roles": ["analyst"],
  "permissions": {
    "dataSources": ["read"],
    "dataAssets": ["read", "create"]
  }
}

获取角色列表

端点: GET /admin/roles

成功响应 (200):

{
  "success": true,
  "roles": [
    {
      "id": "admin",
      "name": "Administrator",
      "description": "Full system access",
      "permissions": ["*"]
    },
    {
      "id": "analyst",
      "name": "Data Analyst", 
      "description": "Data access and analysis",
      "permissions": [
        "data-sources:read",
        "data-assets:read",
        "data-assets:create",
        "datoms:query"
      ]
    }
  ]
}

AI Agent API

聊天查询

端点: POST /agents/chat

请求体:

{
  "message": "显示过去一周的用户登录趋势",
  "database": "user_analytics",
  "context": {
    "previousQueries": [],
    "preferredFormat": "table"
  }
}

成功响应 (200):

{
  "success": true,
  "response": {
    "answer": "根据数据分析，过去一周用户登录呈现上升趋势...",
    "query": "[:find ?date (count ?user) :where [?e :user_id ?user] [?e :event \"login\"] [?e :timestamp ?t] [(>= ?t \"2024-12-21\")] [(format-date ?t \"YYYY-MM-DD\" ?date)] :group-by ?date]",
    "data": [
      ["2024-12-22", 1250],
      ["2024-12-23", 1380],
      ["2024-12-24", 1150]
    ],
    "visualization": {
      "type": "line_chart",
      "config": {
        "x": "date",
        "y": "login_count",
        "title": "Weekly Login Trend"
      }
    }
  },
  "executionTime": 1500
}

执行 Agent

端点: POST /agents/execute

请求体:

{
  "agent": "dataAnalysisAgent",
  "task": "analyze_user_behavior",
  "parameters": {
    "timeRange": "7d",
    "metrics": ["login", "purchase", "session_duration"],
    "groupBy": "daily"
  },
  "database": "user_analytics"
}

文件管理 API

上传文件

端点: POST /files/upload

请求头:

Content-Type: multipart/form-data
Authorization: Bearer <token>

表单数据:

file: 文件内容
category (可选): 文件分类
description (可选): 文件描述

成功响应 (200):

{
  "success": true,
  "file": {
    "id": "file_1234567890",
    "filename": "sales_data.csv",
    "originalName": "Q4_Sales_Report.csv",
    "size": 2048576,
    "mimeType": "text/csv",
    "hash": "a1b2c3d4e5f6...",
    "uploadedAt": "2024-12-28T16:00:00.000Z",
    "url": "/api/files/file_1234567890/download"
  }
}

获取文件列表

端点: GET /files

查询参数:

category: 文件分类过滤
mimeType: MIME 类型过滤
search: 文件名搜索

成功响应 (200):

{
  "success": true,
  "files": [
    {
      "id": "file_1234567890",
      "filename": "sales_data.csv",
      "size": 2048576,
      "mimeType": "text/csv",
      "uploadedAt": "2024-12-28T16:00:00.000Z"
    }
  ]
}

下载文件

端点: GET /files/{id}/download

响应: 文件二进制内容

系统管理 API

系统健康检查

端点: GET /health

成功响应 (200):

{
  "status": "ok",
  "version": "0.1.0",
  "timestamp": "2024-12-28T16:00:00.000Z",
  "uptime": 3600,
  "memory": {
    "used": "125MB",
    "total": "512MB",
    "percentage": 24.4
  },
  "services": {
    "database": "ok",
    "fileStorage": "ok",
    "aiService": "ok"
  }
}

系统统计

端点: GET /admin/stats

权限要求: admin 角色

成功响应 (200):

{
  "success": true,
  "stats": {
    "dataSources": {
      "total": 15,
      "active": 12,
      "byType": {
        "mysql": 5,
        "postgresql": 3,
        "mongodb": 2,
        "files": 5
      }
    },
    "dataAssets": {
      "total": 45,
      "totalSize": "2.5GB",
      "totalRecords": 1250000
    },
    "users": {
      "total": 25,
      "active": 23,
      "lastDay": 8
    },
    "api": {
      "requestsToday": 2540,
      "avgResponseTime": 45,
      "errorRate": 0.2
    }
  }
}

错误代码说明

HTTP 状态码

200 OK: 请求成功
201 Created: 资源创建成功
400 Bad Request: 请求参数错误
401 Unauthorized: 未认证或认证失败
403 Forbidden: 权限不足
404 Not Found: 资源不存在
409 Conflict: 资源冲突（如重复创建）
422 Unprocessable Entity: 请求数据验证失败
500 Internal Server Error: 服务器内部错误
503 Service Unavailable: 服务不可用

业务错误代码

{
  "success": false,
  "error": {
    "code": "DATA_SOURCE_CONNECTION_FAILED",
    "message": "无法连接到数据源",
    "details": {
      "host": "mysql.example.com",
      "error": "Connection timeout"
    }
  }
}

常见错误代码:

INVALID_CREDENTIALS: 登录凭证无效
INSUFFICIENT_PERMISSIONS: 权限不足
DATA_SOURCE_NOT_FOUND: 数据源不存在
DATA_SOURCE_CONNECTION_FAILED: 数据源连接失败
INVALID_QUERY: 查询语法错误
DATABASE_NOT_FOUND: 数据库不存在
TRANSACTION_FAILED: 事务执行失败
FILE_UPLOAD_FAILED: 文件上传失败
VALIDATION_ERROR: 数据验证失败
RATE_LIMIT_EXCEEDED: 请求频率超限

错误处理示例

// JavaScript 错误处理示例
try {
  const response = await fetch('/api/data-sources', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(dataSource)
  });
  
  const result = await response.json();
  
  if (!response.ok) {
    throw new Error(result.error?.message || 'Request failed');
  }
  
  return result.data;
} catch (error) {
  console.error('API Error:', error.message);
  // 处理具体错误类型
  if (error.message.includes('connection')) {
    // 处理连接错误
  }
}

目录​

认证 (Authentication)​

获取访问令牌​

令牌验证​

数据源管理 API​

获取数据源列表​

创建数据源​

测试数据源连接​

获取数据源数据预览​

数据资产管理 API​

获取数据资产列表​

创建数据资产​

获取数据资产详情​

DatomsDB 操作 API​

获取数据库列表​

创建数据库​

执行查询​

执行事务​

用户与权限管理 API​

获取用户列表​

创建用户​

获取角色列表​

AI Agent API​

聊天查询​

执行 Agent​

文件管理 API​

上传文件​

获取文件列表​

下载文件​

系统管理 API​

系统健康检查​

系统统计​

错误代码说明​

HTTP 状态码​

业务错误代码​

错误处理示例​

目录

认证 (Authentication)

获取访问令牌

令牌验证

数据源管理 API

获取数据源列表

创建数据源

测试数据源连接

获取数据源数据预览

数据资产管理 API

获取数据资产列表

创建数据资产

获取数据资产详情

DatomsDB 操作 API

获取数据库列表

创建数据库

执行查询

执行事务

用户与权限管理 API

获取用户列表

创建用户

获取角色列表

AI Agent API

聊天查询

执行 Agent

文件管理 API

上传文件

获取文件列表

下载文件

系统管理 API

系统健康检查

系统统计

错误代码说明

HTTP 状态码

业务错误代码

错误处理示例