第一次提交
This commit is contained in:
670
backend/API_DOCUMENTATION.md
Normal file
670
backend/API_DOCUMENTATION.md
Normal file
@@ -0,0 +1,670 @@
|
||||
# API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
低代码智能体平台提供RESTful API和WebSocket API，支持工作流管理、执行管理、数据源管理等功能。
|
||||
|
||||
**Base URL**: `http://localhost:8037` 或 `http://101.43.95.130:8037`
|
||||
|
||||
**API版本**: v1
|
||||
|
||||
**文档地址**:
|
||||
- Swagger UI: `http://localhost:8037/docs`
|
||||
- ReDoc: `http://localhost:8037/redoc`
|
||||
|
||||
## 认证
|
||||
|
||||
大部分API需要JWT认证。认证流程：
|
||||
|
||||
1. 用户注册或登录获取token
|
||||
2. 在请求头中添加：`Authorization: Bearer <token>`
|
||||
|
||||
### 获取Token
|
||||
|
||||
```http
|
||||
POST /api/v1/auth/login
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
username=your_username&password=your_password
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer"
|
||||
}
|
||||
```
|
||||
|
||||
## API端点
|
||||
|
||||
### 认证API (`/api/v1/auth`)
|
||||
|
||||
#### 用户注册
|
||||
```http
|
||||
POST /api/v1/auth/register
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "testuser",
|
||||
"email": "test@example.com",
|
||||
"password": "password123"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 201 Created
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"username": "testuser",
|
||||
"email": "test@example.com",
|
||||
"role": "user",
|
||||
"created_at": "2024-01-01T00:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### 用户登录
|
||||
```http
|
||||
POST /api/v1/auth/login
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
username=testuser&password=password123
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer"
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取当前用户信息
|
||||
```http
|
||||
GET /api/v1/auth/me
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"username": "testuser",
|
||||
"email": "test@example.com",
|
||||
"role": "user"
|
||||
}
|
||||
```
|
||||
|
||||
### 工作流API (`/api/v1/workflows`)
|
||||
|
||||
#### 获取工作流列表
|
||||
```http
|
||||
GET /api/v1/workflows?skip=0&limit=10&search=关键词&status=draft&sort_by=created_at&sort_order=desc
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
- `skip`: 跳过记录数（分页，默认0）
|
||||
- `limit`: 每页记录数（默认100，最大100）
|
||||
- `search`: 搜索关键词（按名称或描述搜索）
|
||||
- `status`: 状态筛选（draft/published/running/stopped）
|
||||
- `sort_by`: 排序字段（name/created_at/updated_at）
|
||||
- `sort_order`: 排序方向（asc/desc）
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "工作流名称",
|
||||
"description": "描述",
|
||||
"nodes": [...],
|
||||
"edges": [...],
|
||||
"version": 1,
|
||||
"status": "draft",
|
||||
"created_at": "2024-01-01T00:00:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 创建工作流
|
||||
```http
|
||||
POST /api/v1/workflows
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "工作流名称",
|
||||
"description": "描述",
|
||||
"nodes": [
|
||||
{
|
||||
"id": "start-1",
|
||||
"type": "start",
|
||||
"position": {"x": 0, "y": 0},
|
||||
"data": {"label": "开始"}
|
||||
}
|
||||
],
|
||||
"edges": []
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 201 Created
|
||||
|
||||
#### 获取工作流详情
|
||||
```http
|
||||
GET /api/v1/workflows/{workflow_id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
|
||||
#### 更新工作流
|
||||
```http
|
||||
PUT /api/v1/workflows/{workflow_id}
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "更新后的名称",
|
||||
"description": "更新后的描述",
|
||||
"nodes": [...],
|
||||
"edges": [...]
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
|
||||
#### 删除工作流
|
||||
```http
|
||||
DELETE /api/v1/workflows/{workflow_id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"message": "工作流已删除"
|
||||
}
|
||||
```
|
||||
|
||||
#### 执行工作流
|
||||
```http
|
||||
POST /api/v1/workflows/{workflow_id}/execute
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"input_data": {
|
||||
"key": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 201 Created
|
||||
```json
|
||||
{
|
||||
"id": "execution_id",
|
||||
"workflow_id": "workflow_id",
|
||||
"status": "pending",
|
||||
"task_id": "celery_task_id"
|
||||
}
|
||||
```
|
||||
|
||||
#### 验证工作流
|
||||
```http
|
||||
POST /api/v1/workflows/validate
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "工作流名称",
|
||||
"nodes": [...],
|
||||
"edges": [...]
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"valid": true,
|
||||
"errors": [],
|
||||
"warnings": []
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取工作流模板列表
|
||||
```http
|
||||
GET /api/v1/workflows/templates
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 从模板创建工作流
|
||||
```http
|
||||
POST /api/v1/workflows/templates/{template_id}/create?name=工作流名称&description=描述
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 导出工作流
|
||||
```http
|
||||
GET /api/v1/workflows/{workflow_id}/export
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"workflow": {...},
|
||||
"exported_at": "2024-01-01T00:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### 导入工作流
|
||||
```http
|
||||
POST /api/v1/workflows/import
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"workflow": {...}
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取工作流版本列表
|
||||
```http
|
||||
GET /api/v1/workflows/{workflow_id}/versions
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 获取工作流版本详情
|
||||
```http
|
||||
GET /api/v1/workflows/{workflow_id}/versions/{version}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 回滚工作流版本
|
||||
```http
|
||||
POST /api/v1/workflows/{workflow_id}/versions/{version}/rollback
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"comment": "回滚原因"
|
||||
}
|
||||
```
|
||||
|
||||
### 执行管理API (`/api/v1/executions`)
|
||||
|
||||
#### 创建执行任务
|
||||
```http
|
||||
POST /api/v1/executions
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"workflow_id": "workflow_id",
|
||||
"input_data": {
|
||||
"key": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 201 Created
|
||||
|
||||
#### 获取执行记录列表
|
||||
```http
|
||||
GET /api/v1/executions?skip=0&limit=10&workflow_id=uuid&status=completed&search=关键词
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
- `skip`: 跳过记录数（分页）
|
||||
- `limit`: 每页记录数（最大100）
|
||||
- `workflow_id`: 工作流ID筛选
|
||||
- `status`: 状态筛选（pending/running/completed/failed）
|
||||
- `search`: 搜索关键词
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"workflow_id": "uuid",
|
||||
"status": "completed",
|
||||
"input_data": {...},
|
||||
"output_data": {...},
|
||||
"execution_time": 1234,
|
||||
"created_at": "2024-01-01T00:00:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 获取执行详情
|
||||
```http
|
||||
GET /api/v1/executions/{execution_id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
|
||||
#### 获取执行状态
|
||||
```http
|
||||
GET /api/v1/executions/{execution_id}/status
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"status": "running",
|
||||
"progress": 50,
|
||||
"current_node": "llm-1"
|
||||
}
|
||||
```
|
||||
|
||||
### 执行日志API (`/api/v1/execution-logs`)
|
||||
|
||||
#### 获取执行日志
|
||||
```http
|
||||
GET /api/v1/execution-logs/executions/{execution_id}?level=info&node_id=node-1&skip=0&limit=100
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
- `level`: 日志级别筛选（info/warn/error/debug）
|
||||
- `node_id`: 节点ID筛选
|
||||
- `skip`: 跳过记录数
|
||||
- `limit`: 每页记录数
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"logs": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"node_id": "node-1",
|
||||
"node_type": "llm",
|
||||
"level": "info",
|
||||
"message": "节点开始执行",
|
||||
"timestamp": "2024-01-01T00:00:00",
|
||||
"duration_ms": 1234
|
||||
}
|
||||
],
|
||||
"total": 100,
|
||||
"skip": 0,
|
||||
"limit": 100
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取执行日志摘要
|
||||
```http
|
||||
GET /api/v1/execution-logs/executions/{execution_id}/summary
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"total_logs": 100,
|
||||
"level_stats": {
|
||||
"info": 80,
|
||||
"warn": 10,
|
||||
"error": 5,
|
||||
"debug": 5
|
||||
},
|
||||
"node_stats": [
|
||||
{
|
||||
"node_id": "node-1",
|
||||
"node_type": "llm",
|
||||
"log_count": 10,
|
||||
"total_duration_ms": 5000
|
||||
}
|
||||
],
|
||||
"error_logs": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### 数据源API (`/api/v1/data-sources`)
|
||||
|
||||
#### 获取数据源列表
|
||||
```http
|
||||
GET /api/v1/data-sources?skip=0&limit=10&type=mysql&status=active
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 创建数据源
|
||||
```http
|
||||
POST /api/v1/data-sources
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "MySQL数据源",
|
||||
"type": "mysql",
|
||||
"description": "描述",
|
||||
"config": {
|
||||
"host": "localhost",
|
||||
"port": 3306,
|
||||
"database": "test",
|
||||
"username": "user",
|
||||
"password": "password"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取数据源详情
|
||||
```http
|
||||
GET /api/v1/data-sources/{data_source_id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 更新数据源
|
||||
```http
|
||||
PUT /api/v1/data-sources/{data_source_id}
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "更新后的名称",
|
||||
"config": {...}
|
||||
}
|
||||
```
|
||||
|
||||
#### 删除数据源
|
||||
```http
|
||||
DELETE /api/v1/data-sources/{data_source_id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
#### 测试数据源连接
|
||||
```http
|
||||
POST /api/v1/data-sources/{data_source_id}/test
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "连接成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 查询数据源数据
|
||||
```http
|
||||
POST /api/v1/data-sources/{data_source_id}/query
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"query": "SELECT * FROM table LIMIT 10"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 200 OK
|
||||
```json
|
||||
{
|
||||
"data": [...],
|
||||
"count": 10
|
||||
}
|
||||
```
|
||||
|
||||
### WebSocket API
|
||||
|
||||
#### 连接WebSocket
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:8037/api/v1/ws/executions/{execution_id}?token=<token>');
|
||||
```
|
||||
|
||||
#### 接收消息
|
||||
```json
|
||||
{
|
||||
"type": "status",
|
||||
"data": {
|
||||
"status": "running",
|
||||
"progress": 50,
|
||||
"current_node": "llm-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误码
|
||||
|
||||
| 状态码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 成功 |
|
||||
| 201 | 创建成功 |
|
||||
| 400 | 请求参数错误 |
|
||||
| 401 | 未授权（需要登录） |
|
||||
| 403 | 禁止访问（权限不足） |
|
||||
| 404 | 资源不存在 |
|
||||
| 422 | 验证错误 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## 错误响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "错误描述",
|
||||
"error_code": "ERROR_CODE",
|
||||
"status_code": 400
|
||||
}
|
||||
```
|
||||
|
||||
## 节点类型
|
||||
|
||||
### 支持的节点类型
|
||||
|
||||
- `start` - 开始节点
|
||||
- `input` - 输入节点
|
||||
- `llm` - LLM节点（调用AI模型）
|
||||
- `condition` - 条件节点（条件判断）
|
||||
- `transform` - 转换节点（数据转换）
|
||||
- `loop` - 循环节点（循环处理）
|
||||
- `agent` - Agent节点（执行智能Agent）
|
||||
- `output` - 输出节点
|
||||
- `end` - 结束节点
|
||||
|
||||
### LLM节点配置
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "llm-1",
|
||||
"type": "llm",
|
||||
"data": {
|
||||
"provider": "deepseek",
|
||||
"model": "deepseek-chat",
|
||||
"prompt": "请回答：{input}",
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 1000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 条件节点配置
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "condition-1",
|
||||
"type": "condition",
|
||||
"data": {
|
||||
"expression": "{value} > 10"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 循环节点配置
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "loop-1",
|
||||
"type": "loop",
|
||||
"data": {
|
||||
"items_path": "items",
|
||||
"item_variable": "item",
|
||||
"error_handling": "continue"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 数据源类型
|
||||
|
||||
支持的数据源类型：
|
||||
|
||||
- `mysql` - MySQL数据库
|
||||
- `postgresql` - PostgreSQL数据库
|
||||
- `api` - RESTful API
|
||||
- `json` - JSON文件
|
||||
|
||||
## 示例
|
||||
|
||||
### 完整工作流示例
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "文本处理工作流",
|
||||
"description": "处理用户输入的文本",
|
||||
"nodes": [
|
||||
{
|
||||
"id": "start-1",
|
||||
"type": "start",
|
||||
"position": {"x": 0, "y": 0},
|
||||
"data": {"label": "开始"}
|
||||
},
|
||||
{
|
||||
"id": "llm-1",
|
||||
"type": "llm",
|
||||
"position": {"x": 200, "y": 0},
|
||||
"data": {
|
||||
"label": "LLM处理",
|
||||
"provider": "deepseek",
|
||||
"model": "deepseek-chat",
|
||||
"prompt": "请总结以下文本：{input}"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "end-1",
|
||||
"type": "end",
|
||||
"position": {"x": 400, "y": 0},
|
||||
"data": {"label": "结束"}
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"id": "e1",
|
||||
"source": "start-1",
|
||||
"target": "llm-1"
|
||||
},
|
||||
{
|
||||
"id": "e2",
|
||||
"source": "llm-1",
|
||||
"target": "end-1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 更多信息
|
||||
|
||||
详细的API文档请访问：
|
||||
- Swagger UI: `http://localhost:8037/docs`
|
||||
- ReDoc: `http://localhost:8037/redoc`
|
||||
Reference in New Issue
Block a user