Outline API开发指南：构建协作式知识管理系统

核心概念

1.1 接口设计理念

Outline API采用RESTful架构风格，旨在提供简洁、一致的接口体验，使开发者能够轻松构建与团队知识库的集成方案。设计遵循以下原则：

• 资源导向：以文档、集合等实体为核心资源
• 无状态交互：每个请求包含完整上下文信息
• 统一接口：标准化的请求/响应格式
• 可缓存性：支持适当的缓存机制提升性能

1.2 基础交互规范

通信基础

• 基础URL：/api
• 认证方式：JWT (JSON Web Token)
• 数据格式：JSON
• 字符编码：UTF-8

标准响应结构

所有API响应遵循一致的JSON结构：

{
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 100
  },
  "data": [],
  "policies": {}
}

注意：pagination字段仅在返回列表数据时出现，policies字段描述当前用户对资源的操作权限。

操作指南

2.1 资源操作

2.1.1 文档查询

POST /api/documents.list - 获取文档列表

前置条件：有效的认证令牌和相应的访问权限

参数说明：

• sort: string - 排序字段，可选值：createdAt, updatedAt, publishedAt, index, title
• direction: string - 排序方向，可选值：ASC, DESC
• collectionId: string - 集合ID，用于筛选特定集合下的文档

使用建议：当需要展示文档列表时，建议使用updatedAt降序排序，以显示最新更新的文档。

请求示例：

try {
  const response = await fetch('/api/documents.list', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_JWT_TOKEN'
    },
    body: JSON.stringify({
      sort: 'updatedAt',
      direction: 'DESC',
      collectionId: 'your-collection-id'
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error.message}`);
  }
  
  const data = await response.json();
  console.log('Documents:', data.data);
} catch (error) {
  console.error('Error fetching documents:', error.message);
}

2.1.2 文档创建

POST /api/documents.create - 创建新文档

前置条件：有效的认证令牌和集合写入权限

参数说明：

• title: string - 文档标题（必填）
• text: string - 文档内容，使用ProseMirror JSON格式（必填）
• collectionId: string - 所属集合ID（必填）
• publish: boolean - 是否发布，默认为false

使用建议：创建重要文档时，建议先设置为草稿（publish: false），完成编辑后再发布。

最佳实践：创建文档时指定有意义的标题和适当的图标，有助于用户快速识别文档内容。

2.1.3 文档更新

POST /api/documents.update - 更新现有文档

前置条件：有效的认证令牌和文档编辑权限

参数说明：

• id: string - 文档ID（必填）
• title: string - 新文档标题
• text: string - 新文档内容
• append: boolean - 是否追加内容，默认为false

使用建议：对于频繁更新的文档，考虑使用append: true模式以保留历史记录。

2.2 状态控制

2.2.1 文档状态流转

文档在其生命周期中会经历多种状态变化，以下是主要状态转换流程：

stateDiagram-v2
    [*] --> Draft
    Draft --> Published: publish
    Published --> Draft: unpublish
    Draft --> Archived: archive
    Published --> Archived: archive
    Archived --> Draft: restore
    Draft --> Deleted: delete
    Published --> Deleted: delete
    Deleted --> Draft: restore

2.2.2 状态操作接口

POST /api/documents.publish - 发布文档

POST /api/documents.unpublish - 取消发布

POST /api/documents.archive - 归档文档

POST /api/documents.restore - 恢复文档

POST /api/documents.delete - 删除文档

参数说明（所有状态接口）：

• id: string - 文档ID（必填）
• permanent: boolean - 是否永久删除，仅delete接口支持，默认为false

警告：使用permanent: true将永久删除文档，此操作不可恢复。

场景实践

3.1 文档管理工作流

以下是一个典型的文档协作流程，涉及多个API接口的组合使用：

sequenceDiagram
    participant User
    participant API
    participant Database
    
    User->>API: 1. 创建文档 (documents.create)
    API->>Database: 存储新文档
    API-->>User: 返回文档信息
    
    User->>API: 2. 更新文档内容 (documents.update)
    API->>Database: 更新文档数据
    API-->>User: 返回更新结果
    
    User->>API: 3. 发布文档 (documents.publish)
    API->>Database: 更新文档状态
    API-->>User: 返回发布结果
    
    User->>API: 4. 获取文档列表 (documents.list)
    API->>Database: 查询文档集合
    API-->>User: 返回文档列表

3.2 权限控制实现

Outline API提供细粒度的权限控制机制，允许对文档设置不同级别的访问权限：

POST /api/documents.add_user - 添加用户权限 POST /api/documents.add_group - 添加组权限

参数说明：

• id: string - 文档ID（必填）
• userId/groupId: string - 用户ID或组ID（必填）
• permission: string - 权限级别，可选值：read, read_write, admin

示例代码：

// 添加用户权限
async function addDocumentPermission(documentId, userId, permission) {
  try {
    const response = await fetch('/api/documents.add_user', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_JWT_TOKEN'
      },
      body: JSON.stringify({
        id: documentId,
        userId: userId,
        permission: permission
      })
    });
    
    if (!response.ok) {
      throw new Error(`权限添加失败: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('操作失败:', error);
    throw error;
  }
}

最佳实践：为团队项目设置适当的权限级别，对敏感文档使用"admin"权限控制，一般参考文档可设置为"read"权限。

问题解决

4.1 常见问题诊断树

4.1.1 认证失败

1. 检查JWT令牌是否过期
   • 是 → 获取新令牌
   • 否 → 检查令牌格式是否正确
2. 验证令牌是否包含必要的权限声明
3. 确认请求头中Authorization字段格式正确（"Bearer {token}"）

4.1.2 权限错误（403）

1. 检查当前用户是否有操作该资源的权限
   • 是 → 检查API端点是否正确
   • 否 → 请求资源所有者添加权限
2. 验证资源ID是否正确
3. 确认资源未被归档或删除

4.2 错误响应处理

API错误响应格式：

{
  "error": {
    "name": "ValidationError",
    "message": "Invalid input provided",
    "status": 422,
    "details": [
      {
        "path": ["title"],
        "message": "Title is required"
      }
    ]
  }
}

错误处理示例：

async function handleApiError(response) {
  const errorData = await response.json();
  
  switch (response.status) {
    case 400:
      console.error('请求参数错误:', errorData.error.details);
      break;
    case 401:
      console.error('认证失败:', errorData.error.message);
      // 触发重新认证流程
      break;
    case 403:
      console.error('权限不足:', errorData.error.message);
      break;
    case 404:
      console.error('资源不存在:', errorData.error.message);
      break;
    case 422:
      console.error('数据验证失败:', errorData.error.details);
      break;
    case 429:
      console.error('请求频率超限，请稍后再试');
      // 实现退避重试逻辑
      break;
    case 500:
      console.error('服务器内部错误:', errorData.error.message);
      break;
    default:
      console.error('API错误:', errorData.error.message);
  }
  
  throw new Error(`${response.status}: ${errorData.error.message}`);
}

4.3 性能优化建议

1. 批量操作：对于多个文档的相同操作，考虑使用批量接口减少请求次数
2. 合理分页：列表查询时使用limit和offset参数控制返回数据量
3. 字段过滤：只请求需要的字段，减少数据传输量
4. 缓存策略：对不常变化的资源实现客户端缓存

扩展阅读：API设计中采用的乐观并发控制机制，通过版本号或时间戳避免多用户编辑冲突。

接口参考

5.1 核心接口速查表

接口	功能	权限要求
POST /api/documents.list	获取文档列表	读权限
POST /api/documents.create	创建文档	写权限
POST /api/documents.info	获取文档详情	读权限
POST /api/documents.update	更新文档	写权限
POST /api/documents.delete	删除文档	管理权限

5.2 接口调用频率限制

• 普通接口：每分钟25次
• 搜索接口：每分钟100次

当超过限制时，API将返回429状态码，响应头中包含Retry-After字段指示重试时间。

5.3 数据模型

文档核心数据模型：

interface Document {
  id: string;
  title: string;
  text: string;
  collectionId: string;
  parentDocumentId?: string;
  createdAt: string;
  updatedAt: string;
  publishedAt?: string;
  archivedAt?: string;
  deletedAt?: string;
  isTemplate: boolean;
  icon?: string;
  color?: string;
}