Outline API开发指南：从基础到高级应用

一、基础指南：API架构与交互规范

1.1 接口设计理念

Outline API采用RESTful设计风格，遵循"资源为中心"的架构原则，通过统一的接口模式实现对知识库资源的管理。核心设计理念包括：

• 无状态通信：每个请求包含完整操作所需的全部信息
• 资源导向：使用名词而非动词定义接口（如/documents而非/getDocuments）
• 操作一致性：通过HTTP方法表达操作意图（GET获取、POST创建、PUT更新、DELETE删除）
• 权限集成：响应中包含资源访问策略，简化客户端权限判断

1.2 基础交互信息

项目	说明
基础URL	/api
认证方式	JWT（JSON Web Token，一种基于JSON的身份验证令牌）
请求格式	JSON
响应格式	JSON
数据交换	UTF-8编码

[!NOTE] 所有API端点均以/api为前缀，确保与前端路由明确区分

1.3 认证流程

目标：获取访问令牌并进行API授权
步骤：

1. 通过登录接口获取JWT令牌

   import axios from 'axios';
   
   async function getAuthToken() {
     const response = await axios.post('/api/auth.login', {
       email: '[e-mail]',
       password: 'yourpassword'
     });
     return response.data.data.token;
   }
   

2. 在后续请求头中附加令牌

   const token = await getAuthToken();
   axios.defaults.headers.common['Authorization'] = `Bearer ${token}`;
   

验证：调用/api/users.me接口，确认返回当前用户信息

1.4 标准响应结构

所有API响应遵循统一格式：

{
  "pagination": {         // 仅列表接口返回
    "offset": 0,          // 当前偏移量
    "limit": 20,          // 每页条数
    "total": 100          // 总记录数
  },
  "data": {},             // 业务数据主体
  "policies": {           // 资源访问权限
    "canRead": true,
    "canUpdate": true
  }
}

二、核心功能：文档管理接口详解

2.1 文档操作：创建与更新

创建文档

适用场景：程序自动生成报告、用户内容提交、模板实例化

参数配置指南：

参数名	类型	必需	描述	示例值
title	string	是	文档标题	"项目周报2023Q4"
text	string	是	内容（ProseMirror JSON格式）	{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"内容"}]}]
collectionId	string	是	所属集合ID	"col_123456"
parentDocumentId	string	否	父文档ID，用于创建子文档	"doc_789012"
publish	boolean	否	是否立即发布	true
icon	string	否	文档图标	"file-text"
color	string	否	图标颜色（十六进制）	"#3B82F6"

实现代码：

async function createDocument(documentData) {
  try {
    const response = await axios.post('/api/documents.create', documentData);
    return response.data.data;
  } catch (error) {
    console.error('创建文档失败:', error.response?.data?.error || error.message);
    throw error;
  }
}

// 使用示例
const newDoc = await createDocument({
  title: "API使用指南",
  text: JSON.stringify({
    type: "doc",
    content: [{
      type: "paragraph",
      content: [{ type: "text", text: "这是通过API创建的文档" }]
    }]
  }),
  collectionId: "col_123456",
  publish: true
});

性能考量：

• 文档内容超过10KB时建议分块处理
• 批量创建文档应控制在每秒5个请求以内
• 复杂内容建议先创建草稿，再异步更新内容

更新文档

参数配置指南：

参数名	类型	必需	描述	示例值
id	string	是	文档ID	"doc_789012"
title	string	否	新标题	"更新后的标题"
text	string	否	新内容	ProseMirror JSON格式
append	boolean	否	是否追加内容	false
publish	boolean	否	是否发布	true

实现代码：

async function updateDocument(documentId, updates) {
  return axios.post('/api/documents.update', {
    id: documentId,
    ...updates
  });
}

2.2 文档操作：查询与删除

获取文档列表

参数配置指南：

参数名	类型	必需	描述	示例值
collectionId	string	否	按集合筛选	"col_123456"
sort	string	否	排序字段	"updatedAt"
direction	string	否	排序方向	"DESC"
limit	number	否	每页条数	50
offset	number	否	偏移量	0

实现代码：

async function getDocuments(filters = {}) {
  const response = await axios.post('/api/documents.list', {
    sort: 'updatedAt',
    direction: 'DESC',
    limit: 20,
    ...filters
  });
  return {
    documents: response.data.data,
    pagination: response.data.pagination
  };
}

删除文档

参数配置指南：

参数名	类型	必需	描述	示例值
id	string	是	文档ID	"doc_789012"
permanent	boolean	否	是否永久删除	false

实现代码：

async function deleteDocument(documentId, permanent = false) {
  return axios.post('/api/documents.delete', {
    id: documentId,
    permanent
  });
}

[!WARNING] 永久删除操作不可恢复，请谨慎使用。建议先使用普通删除（放入回收站）

三、高级应用：权限控制与批量操作

3.1 文档权限管理

权限层级说明

Outline API定义三种权限级别：

• read：仅查看权限
• read_write：可编辑但不可管理权限
• admin：完全控制权，包括权限管理

添加用户权限

参数配置指南：

参数名	类型	必需	描述	示例值
id	string	是	文档ID	"doc_789012"
userId	string	是	用户ID	"user_345678"
permission	string	是	权限级别	"read_write"

实现代码：

async function addDocumentPermission(documentId, userId, permission) {
  return axios.post('/api/documents.add_user', {
    id: documentId,
    userId,
    permission
  });
}

3.2 批量文档操作

批量移动文档

适用场景：重组知识库结构、批量整理内容

参数配置指南：

参数名	类型	必需	描述	示例值
documentIds	array	是	文档ID列表	["doc_123", "doc_456"]
collectionId	string	是	目标集合ID	"col_789"
parentDocumentId	string	否	目标父文档ID	null

实现代码：

async function batchMoveDocuments(documentIds, collectionId, parentDocumentId = null) {
  return axios.post('/api/documents.batch_move', {
    documentIds,
    collectionId,
    parentDocumentId
  });
}

性能考量：

• 单次批量操作建议不超过50个文档
• 批量操作会触发多次数据库事务，建议在非高峰时段执行
• 操作结果通过异步任务完成，需轮询任务状态

四、最佳实践：错误处理与性能优化

4.1 错误排查流程

graph TD
    A[发起API请求] --> B{收到响应}
    B -->|状态码2xx| C[处理成功]
    B -->|状态码4xx| D[客户端错误]
    B -->|状态码5xx| E[服务器错误]
    
    D --> F{错误类型}
    F -->|401| G[重新认证]
    F -->|403| H[检查权限]
    F -->|404| I[验证资源ID]
    F -->|422| J[验证请求参数]
    
    E --> K[重试请求]
    K -->|3次失败| L[记录错误并通知管理员]

4.2 常见错误解决方案

错误码	可能原因	解决方案
401	令牌过期或无效	重新获取令牌
403	权限不足	检查用户角色和资源权限设置
422	参数验证失败	检查请求体格式和必填字段
429	请求频率超限	实现请求限流机制，遵守速率限制

4.3 性能优化策略

1. 请求合并：将多个独立请求合并为批量操作
2. 分页查询：列表接口始终使用分页，避免一次性加载过多数据
3. 字段过滤：只请求需要的字段，减少数据传输量
4. 缓存策略：对不常变化的资源实现本地缓存
5. 异步处理：耗时操作（如导出、导入）使用异步任务模式

4.4 API调用频率限制

[!NOTE] Outline API实施以下速率限制：

• 普通接口：每分钟25次请求
• 搜索接口：每分钟100次请求
• 批量操作：每小时100次请求

五、接口演进路线

timeline
    title Outline API版本演进
    2023 Q1 : v1.0 - 基础文档CRUD接口
    2023 Q2 : v1.1 - 添加权限管理功能
    2023 Q3 : v1.2 - 引入批量操作API
    2023 Q4 : v2.0 - 支持实时协作功能
    2024 Q1 : v2.1 - 增强搜索能力，支持全文检索
    2024 Q2 : v3.0 - 引入AI辅助接口，支持智能摘要

六、完整应用示例

以下是一个完整的文档管理工作流示例：

// 1. 认证
const token = await getAuthToken();
axios.defaults.headers.common['Authorization'] = `Bearer ${token}`;

// 2. 创建文档
const doc = await createDocument({
  title: "项目规划",
  text: JSON.stringify({
    type: "doc",
    content: [{
      type: "heading",
      attrs: { level: 1 },
      content: [{ type: "text", text: "项目规划文档" }]
    }]
  }),
  collectionId: "col_123456"
});

// 3. 设置权限
await addDocumentPermission(doc.id, "user_789", "read_write");

// 4. 获取更新后的文档详情
const documentDetails = await axios.post('/api/documents.info', {
  id: doc.id
});

// 5. 批量移动相关文档
await batchMoveDocuments(
  [doc.id, "doc_456", "doc_789"], 
  "col_new_collection"
);

通过这套API，开发者可以灵活构建与Outline知识库的集成，实现自动化文档管理、第三方系统对接等高级功能。随着API的不断演进，还将支持更多智能化特性，为团队协作提供更强大的技术支持。