docyrus-api-dev

Docyrus API 开发者

使用 @docyrus/api-client（REST 客户端）和 @docyrus/signin（React 认证提供程序）集成 Docyrus API。通过 OAuth2 PKCE 进行身份验证，使用强大的筛选和聚合功能查询数据源，并调用 REST 端点。

快速开始身份验证

React 应用 — 使用 @docyrus/signin

import { DocyrusAuthProvider, useDocyrusAuth, useDocyrusClient, SignInButton } from '@docyrus/signin'

// 1. Wrap root
<DocyrusAuthProvider
  apiUrl={import.meta.env.VITE_API_BASE_URL}
  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
  callbackPath="/auth/callback"
>
  <App />
</DocyrusAuthProvider>

// 2. Use hooks
function App() {
  const { status, signOut } = useDocyrusAuth()
  const client = useDocyrusClient()  // RestApiClient | null

  if (status === 'loading') return <Spinner />
  if (status === 'unauthenticated') return <SignInButton />

  // client is ready — make API calls
  const user = await client!.get('/v1/users/me')
}

非 React 应用 / 服务端 — 直接使用 OAuth2Client

import { RestApiClient, OAuth2Client, OAuth2TokenManagerAdapter, BrowserOAuth2TokenStorage } from '@docyrus/api-client'

const tokenStorage = new BrowserOAuth2TokenStorage(localStorage)
const oauth2 = new OAuth2Client({
  baseURL: 'https://api.docyrus.com',
  clientId: 'your-client-id',
  redirectUri: 'http://localhost:3000/callback',
  usePKCE: true,
  tokenStorage,
})

// Auth Code flow
const { url } = await oauth2.getAuthorizationUrl({ scope: 'openid offline_access Users.Read' })
window.location.href = url
// After redirect:
const tokens = await oauth2.handleCallback(window.location.href)

// Create API client with auto-refresh
const client = new RestApiClient({
  baseURL: 'https://api.docyrus.com',
  tokenManager: new OAuth2TokenManagerAdapter(tokenStorage, async () => {
    return (await oauth2.refreshAccessToken()).accessToken
  }),
})

API 端点

数据源项目（因租户而异）

GET    /v1/apps/{appSlug}/data-sources/{slug}/items          — List with query payload
GET    /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Get one
POST   /v1/apps/{appSlug}/data-sources/{slug}/items          — Create
PATCH  /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Update
DELETE /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Delete one
DELETE /v1/apps/{appSlug}/data-sources/{slug}/items          — Delete many (body: { recordIds })

只有在租户中定义了数据源后，才会存在相应端点。请通过 GET /v1/api/openapi.json 查看租户的 OpenAPI 规范。

系统端点（始终可用）

GET    /v1/users          — List users
POST   /v1/users          — Create user
GET    /v1/users/me       — Current user profile
PATCH  /v1/users/me       — Update current user

连接器发现与外部请求端点

GET    /v1/connectors?q=&limit=&offset=                                    — List connectors with keyword search
GET    /v1/connectors/{dataProviderSlug}                                    — Get connector detail (dataSources + actions)
GET    /v1/connectors/{dataProviderSlug}/actions/{actionKey}                — Get action detail (input/output schemas, API endpoint)
GET    /v1/connectors/{dataProviderSlug}/connections                        — Get tenant connections + user connection status
PUT    /v1/connectors/{dataProviderSlug}                                    — Send HTTP request through connector provider auth

作用域：Read.All、ReadWrite.All 或 Connectors.Read.All。PUT 端点需要 ReadWrite.All。

用于通过连接器发送请求的 PUT 请求正文：

{
  "endpoint": "relative/path/or/absolute-url",
  "requestMethod": "GET",
  "data": { "fields": "id,name", "limit": 20 },
  "contentType": "application/json",
  "headers": { "Authorization": "Bearer <override-token>" },
  "connectionId": "optional-tenant-connection-uuid",
  "connectionAccountId": "optional-connection-account-uuid"
}

连接器会从提供方配置和已存储的连接中解析身份验证凭据（OAuth 令牌、基础 URL）。自定义的 headers.Authorization 会覆盖已存储的令牌。

操作运行端点

GET    /v1/apps/base/actions                                               — List base actions
GET    /v1/apps/{appSlug}/actions/{actionSlug}                             — Get action metadata
POST   /v1/apps/{appSlug}/actions/{actionSlug}/run                         — Run action directly

操作运行接受任意 JSON 正文作为输入。可选请求头：x-connection-id、x-connection-account-id。

ACL / 角色管理端点

GET    /v1/users/acl?dataSourceId={uuid}&recordId={uuid}   — Read record ACL rows
POST   /v1/users/acl/share                                 — Upsert record shares
DELETE /v1/users/acl/share                                 — Revoke record shares
PUT    /v1/users/acl/owner                                 — Transfer record ownership

GET    /v1/users/acl/roles                                 — List roles
GET    /v1/users/acl/roles/{roleId}                        — Get one role
POST   /v1/users/acl/roles                                 — Create role
PATCH  /v1/users/acl/roles/{roleId}                        — Update role
DELETE /v1/users/acl/roles/{roleId}                        — Delete role

GET    /v1/users/acl/user-roles                            — List user-role assignments
GET    /v1/users/acl/users/{userId}/roles                  — List one user's roles
POST   /v1/users/acl/users/{userId}/roles                  — Add roles to a user
PUT    /v1/users/acl/users/{userId}/roles                  — Replace a user's full role set
DELETE /v1/users/acl/users/{userId}/roles/{roleId}         — Remove one role assignment

GET    /v1/users/acl/role-queries                          — List role queries
GET    /v1/users/acl/role-queries/{roleQueryId}            — Get one role query
POST   /v1/users/acl/role-queries                          — Create role query
PATCH  /v1/users/acl/role-queries/{roleQueryId}            — Update role query
DELETE /v1/users/acl/role-queries/{roleQueryId}            — Delete role query

ACL 路由需要使用常规的已认证 API 会话，但它们可能不会显示在生成的 Swagger/OpenAPI 输出中，因为后端目前会将其排除在公开文档之外。当你需要记录共享、角色 CRUD、用户角色分配管理或角色查询管理时，请使用直接的 RestApiClient 调用集成这些路由。

对于所有 ACL 角色操作，优先使用 API 返回的角色 uid 值。嵌套角色对象同时包含 id 和 uid，且二者都映射到角色 UID 值。

要配置 ACL（创建角色、分配操作级权限、构建角色查询和组织层级），请使用 docyrus-acl-design skill（docyrus acl …）。上述端点是用于应用 / 前端集成的运行时 REST 接口。

发起 API 调用

// List items with query payload
const items = await client.get('/v1/apps/base/data-sources/project/items', {
  columns: 'name, status, record_owner(firstname,lastname)',
  filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
  orderBy: 'created_on DESC',
  limit: 50,
})

// Get single item
const item = await client.get('/v1/apps/base/data-sources/project/items/uuid-here', {
  columns: 'name, description, status',
})

// Create
const newItem = await client.post('/v1/apps/base/data-sources/project/items', {
  name: 'New Project',
  status: 'status-enum-id',
})

// Update
await client.patch('/v1/apps/base/data-sources/project/items/uuid-here', {
  name: 'Updated Name',
})

// Delete
await client.delete('/v1/apps/base/data-sources/project/items/uuid-here')

查询载荷概要

GET 项目端点接受强大的查询载荷：

功能	用途
columns	选择字段、展开关联 field(subfields)、设置别名 alias:field、展开字段 ...field()
filters	使用 50 多种运算符（比较、日期快捷方式、用户相关）构建嵌套 AND/OR 分组
filterKeyword	在所有可搜索字段中进行全文搜索
orderBy	按字段排序并指定方向，包括关联字段
limit/offset	分页（默认 limit：100）
fullCount	返回结果的同时返回匹配总数
calculations	聚合：按分组进行 count、sum、avg、min、max
formulas	计算虚拟列（简单函数、块 AST、相关子查询）
childQueries	以嵌套 JSON 数组的形式获取相关子记录
pivot	使用日期范围序列进行交叉表矩阵查询
expand	为关联 / 用户 / 枚举字段返回完整对象，而非 ID

完整的查询和公式参考，请阅读：

• references/data-source-query-guide.md
• references/formula-design-guide-llm.md

关键规则

1. 在列表／获取调用中始终发送 columns。否则只会返回 id。
2. 数据源端点是动态的——只有租户中定义的数据源才有对应端点。
3. 计算 count 时使用 id 字段。计算 sum、avg、min、max 时使用实际字段 slug。
4. 子查询键必须出现在 columns 中——如果 childQuery 键是 orders，请在 columns 中包含 orders。
5. 公式键必须出现在 columns 中——如果公式键是 total，请在 columns 中包含 total。
6. 按关联字段筛选时使用 rel_{{relation_field}}/{{field}} 语法。
7. ACL 路由可能不会显示在生成的 OpenAPI 中——请改用 RestApiClient 直接调用，不要依赖生成的集合支持。
8. 在 ACL 角色写入、用户角色 roleIds 和角色查询 roleIds 中，优先使用角色的 uid 值。
9. 将 PUT /v1/users/acl/users/:userId/roles 视为完整替换操作，将 POST /v1/users/acl/users/:userId/roles 视为增量添加操作。
10. 将角色查询的 query 作为原始 JSON 发送；在适用时，由后端根据 dataSourceId 推导 tenantAppId。
11. 删除角色后，刷新依赖的 ACL 状态——角色列表、用户角色列表、角色查询列表，以及所有显示主角色标签的 UI。

参考资料

需要详细信息时，请阅读以下文件：

• references/api-client.md——完整的 RestApiClient API、OAuth2Client（所有流程：PKCE、客户端凭据、设备代码）、令牌管理器、拦截器、错误类、SSE／流式传输、文件上传／下载、HTML 转 PDF、重试逻辑
• references/authentication.md——@docyrus/signin React 提供程序、useDocyrusAuth/useDocyrusClient hooks、hasRole/hasPermission 授权辅助函数、SignInButton、独立与 iframe 身份验证模式、环境变量、API 客户端访问模式
• references/data-source-query-guide.md——最新查询负载指南：columns、筛选条件、orderBy、分页、计算、公式、子查询、透视表和运算符参考
• references/formula-design-guide-llm.md——最新公式设计指南，介绍如何构建和验证 formulas 负载