Outline API开发指南：从基础到实战

核心概念：API交互基础

RESTful API工作原理

想象API是一个虚拟的文件柜，每个文档就像一个文件。当你需要操作文件时，你会：

• 查看文件列表（对应GET /documents）
• 打开特定文件（对应GET /documents/{id}）
• 添加新文件（对应POST /documents）
• 修改文件内容（对应PATCH /documents/{id}）
• 删除文件（对应DELETE /documents/{id}）

这种"文件柜操作"模式就是RESTful API的核心思想——使用标准HTTP方法对资源进行CRUD（创建、读取、更新、删除）操作。

图1：Outline项目logo，象征知识管理与文档协作

基础交互要素

要素	说明	示例
基础URL	API请求的起点	/api
认证方式	身份验证机制	JWT（JSON Web Token）
数据格式	请求/响应的数据交换格式	JSON
状态码	操作结果的数字标识	200（成功）、404（未找到）

API调用决策树

flowchart TD
    A[需要操作什么资源?] -->|文档| B[文档操作]
    A -->|集合| C[集合操作]
    A -->|用户| D[用户操作]
    B --> E{操作类型?}
    E -->|创建| F[POST /documents.create]
    E -->|查询| G[POST /documents.list 或 /documents.info]
    E -->|更新| H[POST /documents.update]
    E -->|删除| I[POST /documents.delete]

操作指南：核心功能实现

如何创建并管理文档

创建新文档

适用场景：团队成员需要添加新的知识库内容，如会议记录、技术规范等。

请求示例：

{
  "title": "2023年Q4技术规划",  // 文档标题，必填
  "text": { "type": "doc", "content": [] },  // ProseMirror JSON格式的文档内容
  "collectionId": "col_123456",  // 所属集合ID，必填
  "publish": true,  // 是否立即发布
  "icon": "file-text",  // 文档图标
  "color": "#3B82F6"  // 图标颜色，十六进制格式
}

响应解析：

{
  "data": {
    "id": "doc_789012",  // 系统生成的唯一文档ID
    "title": "2023年Q4技术规划",
    "createdAt": "2023-10-01T10:00:00Z",  // 创建时间戳
    "collectionId": "col_123456"
  }
}

注意事项：

• 文档内容需使用ProseMirror JSON格式
• 若不指定id，系统会自动生成UUID
• publish为true时会立即设置publishedAt字段

查询文档内容

适用场景：获取单个文档的详细内容，包括修订历史和评论。

请求示例：

{
  "id": "doc_789012",  // 文档ID，必填
  "apiVersion": 2  // 使用v2 API获取更丰富的元数据
}

响应解析：

{
  "data": {
    "document": {
      "id": "doc_789012",
      "title": "2023年Q4技术规划",
      "text": { "type": "doc", "content": [...] },  // 完整文档内容
      "revisions": [...],  // 修订历史记录
      "comments": [...]  // 文档评论
    }
  },
  "policies": {
    "canRead": true,  // 当前用户是否有读取权限
    "canUpdate": true,  // 当前用户是否有更新权限
    "canDelete": false  // 当前用户是否有删除权限
  }
}

知识检查：如何判断当前用户是否有权限编辑某个文档？

批量操作与异步任务

批量移动文档

适用场景：重组知识库结构时，将多个文档移动到新的集合或父文档下。

请求示例：

{
  "documentIds": ["doc_1", "doc_2", "doc_3"],  // 要移动的文档ID列表
  "collectionId": "new_col_456",  // 目标集合ID
  "parentDocumentId": "parent_doc_789"  // 可选的目标父文档ID
}

响应解析：

{
  "data": {
    "taskId": "task_123456",  // 异步任务ID
    "status": "processing",  // 任务状态：processing/success/failed
    "progress": 0.3  // 任务进度（0-1）
  }
}

监控异步任务状态

适用场景：获取批量操作、文档导入等耗时任务的实时进度。

请求示例：

{
  "taskId": "task_123456"  // 任务ID，从创建任务的响应中获取
}

响应解析：

{
  "data": {
    "id": "task_123456",
    "status": "success",  // 任务已完成
    "progress": 1.0,
    "result": {
      "successCount": 3,  // 成功处理的文档数量
      "failedCount": 0   // 处理失败的文档数量
    }
  }
}

进阶场景：权限与集成

文档权限精细化管理

不同场景下的认证策略对比

场景	认证方式	适用范围	安全级别
内部应用	JWT令牌	所有API端点	高
公开分享	shareId参数	仅文档查看	低
移动应用	OAuth2.0	所有API端点	中

添加用户权限示例

请求示例：

{
  "id": "doc_789012",  // 文档ID
  "userId": "user_456",  // 用户ID
  "permission": "read_write"  // 权限级别：read/read_write/admin
}

⚠️ 警告：赋予admin权限意味着用户可以修改文档权限设置，请谨慎操作。

前端集成最佳实践

请求封装示例（JavaScript）

class OutlineAPI {
  constructor(baseUrl, token) {
    this.baseUrl = baseUrl;
    this.token = token;
  }

  async request(endpoint, data) {
    const response = await fetch(`${this.baseUrl}/${endpoint}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`
      },
      body: JSON.stringify(data)
    });

    const result = await response.json();
    
    if (!response.ok) {
      throw new Error(result.error?.message || 'API请求失败');
    }
    
    return result;
  }

  // 文档创建快捷方法
  createDocument(documentData) {
    return this.request('documents.create', documentData);
  }
  
  // 其他API方法...
}

// 使用示例
const api = new OutlineAPI('/api', 'your-jwt-token');
api.createDocument({
  title: '新文档',
  collectionId: 'col_123'
})
.then(data => console.log('文档创建成功:', data))
.catch(error => console.error('创建失败:', error));

问题排查：错误处理与调试

常见错误代码速查表

状态码	含义	可能原因	解决方法
400	请求参数错误	缺少必填字段或格式错误	检查请求体是否符合API要求
401	未授权	令牌过期或无效	重新获取JWT令牌
403	权限不足	用户没有操作资源的权限	联系管理员提升权限
404	资源不存在	请求的文档/集合ID不存在	检查资源ID是否正确
422	验证错误	数据验证失败	根据错误详情修正数据格式
429	请求频率超限	短时间内请求次数过多	实现请求限流机制

API调用调试流程

flowchart TD
    A[发起API请求] --> B{收到响应?}
    B -->|是| C{状态码是否2xx?}
    B -->|否| D[检查网络连接]
    C -->|是| E[处理响应数据]
    C -->|否| F[查看错误详情]
    F --> G[匹配错误代码表]
    G --> H[应用解决方案]
    H --> I[重试请求]

接口版本演进说明

API版本	主要变化	兼容性
v1	基础文档操作功能	已过时，不推荐使用
v2	增加修订历史和评论支持	完全兼容v1，推荐使用
v3	新增批量操作和异步任务	部分接口不兼容v2，需注意变更日志

注意：使用v3 API时，documents.info接口返回格式有重大变化，需更新响应处理逻辑。

总结

本指南通过"核心概念-操作指南-进阶场景-问题排查"四个模块，全面介绍了Outline API的使用方法。从基础的文档CRUD操作到复杂的权限管理和批量任务，开发者可以根据实际需求选择合适的接口和集成策略。

记住，在进行破坏性操作（如删除文档）前，务必确认操作意图和权限，建议先创建备份或使用回收站功能。通过合理利用Outline API，可以将知识库功能无缝集成到各种工作流和第三方系统中，提升团队协作效率。

知识检查答案：通过响应中的policies对象查看canUpdate字段的值，为true表示有编辑权限。