API 参考

Drubase One REST API 完整文档。

🎯 概述

Drubase One 提供完整的 RESTful API，支持：

• 用户认证和授权
• 动态实体 CRUD 操作
• 文件上传和管理
• 实时通信（WebSocket）
• 自定义函数执行

🔗 基础 URL

http://YOUR_HOST/api/v1

🔐 认证

所有 API 请求需要认证，支持两种方式：

JWT Token（推荐）：

Authorization: Bearer YOUR_JWT_TOKEN

API Key：

X-API-Key: YOUR_API_KEY

📚 API 分类

认证 API

用户登录、登出、Token 刷新、角色管理等。

主要端点：

• POST /api/v1/baas/password/verify - 实体用户密码验证（前端登录）
• POST /api/auth/login - Drupal 用户登录
• GET /api/auth/me - 获取当前用户
• POST /api/auth/refresh - 刷新 Token
• GET /api/auth/permissions - 获取权限列表

实体 API

动态实体数据的增删改查操作，包含文件上传。

主要端点：

• GET /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name} - 查询列表
• GET /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}/{id} - 获取单个
• POST /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name} - 创建（支持文件上传）
• PUT /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}/{id} - 更新
• POST /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}/{id}/upload - 更新（带文件上传）
• DELETE /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}/{id} - 删除

💡 提示：文件和媒体资源通过实体 API 操作，使用 multipart/form-data 上传。

API 网关

统一的 API 入口、速率限制、健康检查。

主要端点：

• GET /api/health - 健康检查
• GET /swagger-ui - Swagger UI 文档
• GET /openapi.json - OpenAPI 规范

🚀 快速开始

1. 获取 API Key

登录后台 → Configuration → BaaS → API Settings → 生成 API Key

2. 用户登录

curl -X POST http://YOUR_HOST/api/auth/login \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "username": "user1",
    "password": "password"
  }'

3. 使用 JWT Token

curl -X GET http://YOUR_HOST/api/auth/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

4. 查询实体数据

curl -X GET \
  "http://YOUR_HOST/api/v1/tenant_7375b0cd/projects/tenant_7375b0cd_project_6888d012be80c/entities/users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

📊 速率限制

速率限制信息在响应头中返回：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067260

🔍 错误响应

统一的错误响应格式：

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

常见 HTTP 状态码：

• 200 - 成功
• 400 - 请求参数错误
• 401 - 未认证
• 403 - 权限不足
• 404 - 资源不存在
• 429 - 请求频率超限
• 500 - 服务器错误

📖 交互式文档

访问 Swagger UI 查看完整的交互式 API 文档：

http://YOUR_HOST/swagger-ui

📖 相关资源

• API 配置 - API 设置
• 速率限制 - 速率限制配置
• CORS 配置 - 跨域配置
• 认证指南 - 创建租户