Outline API 完全指南：从基础集成到高级应用

一、核心概念

1.1 API架构概览

Outline API采用RESTful设计原则，提供了一套完整的接口体系，使开发者能够与团队知识库进行深度交互。API以/api为基础路径，采用JSON格式进行数据交换，通过JWT（JSON Web Token）实现身份验证。

1.2 数据模型

Outline API围绕以下核心实体构建：

• 文档(Document)：知识库的基本单元，包含标题、内容、元数据等信息
• 集合(Collection)：文档的组织单元，用于对文档进行分类管理
• 用户(User)：系统的使用者，拥有不同的权限级别
• 组(Group)：用户的集合，便于进行批量权限管理

1.3 认证机制

Outline API使用JWT进行认证，流程如下：

1. 用户通过登录接口获取JWT令牌
2. 在后续请求中，通过Authorization头传递令牌
3. 服务器验证令牌有效性并确定用户权限

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: 提交登录凭据
    Server->>Client: 返回JWT令牌
    Client->>Server: 请求API(带JWT令牌)
    Server->>Server: 验证令牌
    Server->>Client: 返回API响应

二、操作指南

2.1 基础交互

2.1.1 认证流程

获取JWT令牌：

cURL请求

curl -X POST https://your-outline-instance.com/api/auth.login \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"your-password"}'

响应示例

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "uuid",
      "name": "用户名",
      "email": "[e-mail]"
    }
  }
}

2.1.2 通用响应格式

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

{
  "pagination": {  // 仅列表接口返回
    "offset": 0,
    "limit": 20,
    "total": 100
  },
  "data": [],      // 实际返回数据
  "policies": {}   // 权限信息
}

2.2 文档管理

2.2.1 创建文档

功能场景：在指定集合中创建新文档，适用于团队知识记录、会议纪要等场景。

请求参数

参数名	类型	描述
title	string	文档标题，必填项，最多255个字符
text	string	文档内容，使用ProseMirror JSON格式
collectionId	string	所属集合ID，必填项
parentDocumentId	string	父文档ID，用于创建子文档
publish	boolean	是否发布，默认为false
icon	string	文档图标，可选值参考系统支持的图标列表
color	string	图标颜色，十六进制格式，如"#000000"

cURL请求

curl -X POST https://your-outline-instance.com/api/documents.create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "title": "API集成指南",
    "text": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"这是一篇API集成指南文档\"}]}]}",
    "collectionId": "collection-uuid",
    "publish": true,
    "icon": "file-text",
    "color": "#4285F4"
  }'

Postman请求

• 方法: POST
• URL: https://your-outline-instance.com/api/documents.create
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer YOUR_JWT_TOKEN
• Body:

{
  "title": "API集成指南",
  "text": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"这是一篇API集成指南文档\"}]}]}",
  "collectionId": "collection-uuid",
  "publish": true
}

响应示例

{
  "data": {
    "id": "document-uuid",
    "title": "API集成指南",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z",
    "publishedAt": "2025-01-01T00:00:00Z",
    "collectionId": "collection-uuid",
    "createdBy": {
      "id": "user-uuid",
      "name": "用户名"
    }
  },
  "policies": {
    "canRead": true,
    "canUpdate": true,
    "canDelete": true
  }
}

常见问题

Q: 创建文档时text字段格式有什么要求？ A: text字段需要使用ProseMirror JSON格式，这是一种结构化的文档表示方式。可以通过Outline编辑器导出示例来了解具体格式。

Q: 如何获取有效的collectionId？ A: 可以通过调用collections.list接口获取所有集合信息，从中选择合适的collectionId。

2.2.2 获取文档列表

功能场景：获取指定条件的文档列表，适用于构建文档管理界面、实现文档搜索功能等场景。

请求参数

参数名	类型	描述
sort	string	排序字段，可选值：createdAt, updatedAt, publishedAt, title
direction	string	排序方向，可选值：ASC, DESC，默认为DESC
collectionId	string	按集合筛选
userId	string	按创建者筛选
statusFilter	array	状态筛选，可选值：published, draft, archived
limit	number	每页条数，默认为20，最大100
offset	number	分页偏移量，默认为0

cURL请求

curl -X POST https://your-outline-instance.com/api/documents.list \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "sort": "updatedAt",
    "direction": "DESC",
    "collectionId": "collection-uuid",
    "statusFilter": ["published"],
    "limit": 10
  }'

响应示例

{
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 42
  },
  "data": [
    {
      "id": "document-uuid-1",
      "title": "API集成指南",
      "updatedAt": "2025-01-01T00:00:00Z",
      "collectionId": "collection-uuid",
      "createdBy": {
        "id": "user-uuid",
        "name": "用户名"
      },
      "icon": "file-text",
      "color": "#4285F4"
    },
    // 更多文档...
  ],
  "policies": {
    "document-uuid-1": {
      "canRead": true,
      "canUpdate": true,
      "canDelete": true
    }
    // 更多权限信息...
  }
}

常见问题

Q: 如何高效分页获取大量文档？ A: 使用limit和offset参数进行分页，建议将limit设置为50-100以减少请求次数。对于非常大的数据集，可以考虑按时间范围分批获取。

Q: 为什么我只能看到部分文档？ A: 文档列表受权限控制，只能看到你有权访问的文档。如果需要访问更多文档，请联系管理员获取相应权限。

2.3 权限控制

2.3.1 文档权限管理

功能场景：管理用户或组对文档的访问权限，适用于团队协作和文档安全控制场景。

请求参数

参数名	类型	描述
id	string	文档ID，必填项
userId	string	用户ID，添加用户权限时必填
groupId	string	组ID，添加组权限时必填
permission	string	权限级别，可选值：read, read_write, admin

cURL请求（添加用户权限）

curl -X POST https://your-outline-instance.com/api/documents.add_user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "id": "document-uuid",
    "userId": "user-uuid",
    "permission": "read_write"
  }'

响应示例

{
  "data": {
    "documentId": "document-uuid",
    "userId": "user-uuid",
    "permission": "read_write"
  }
}

权限控制模型

graph TD
    A[文档所有者] -->|admin| X[完全控制权]
    B[管理员角色] -->|admin| X
    C[编辑者角色] -->|read_write| Y[读写权限]
    D[查看者角色] -->|read| Z[只读权限]
    X --> 管理权限
    X --> 编辑内容
    X --> 查看内容
    Y --> 编辑内容
    Y --> 查看内容
    Z --> 查看内容

常见问题

Q: 权限级别之间有什么区别？ A: read权限允许查看文档；read_write权限允许查看和编辑文档；admin权限除了查看和编辑外，还可以管理文档权限和删除文档。

Q: 如何批量设置文档权限？ A: 目前API不直接支持批量设置权限，可以通过循环调用权限设置接口来实现。对于大量文档，建议使用组权限而非单独设置用户权限。

三、高级特性

3.1 接口设计理念

3.1.1 RESTful规范实践

Outline API严格遵循RESTful设计原则，主要体现在：

• 资源导向：所有API围绕资源设计，如/api/documents、/api/collections
• HTTP方法语义：虽然使用POST作为统一方法，但在请求体中通过动作名称（如create、update）体现语义
• 状态码使用：遵循HTTP标准状态码，如200表示成功，401表示未授权，403表示权限不足
• 一致的数据格式：所有响应采用相同的JSON结构，便于客户端处理

3.1.2 批量操作

对于需要同时处理多个资源的场景，Outline API提供了批量操作能力：

批量获取文档详情

curl -X POST https://your-outline-instance.com/api/documents.batchInfo \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "ids": ["doc-id-1", "doc-id-2", "doc-id-3"]
  }'

💡 性能提示：使用批量接口可以显著减少API调用次数，建议在需要处理多个资源时优先使用批量接口。

3.2 搜索功能

3.2.1 高级搜索

Outline API提供强大的搜索功能，支持按标题、内容、创建者等多维度搜索：

请求参数

参数名	类型	描述
query	string	搜索关键词，必填项
collectionId	string	限制在特定集合中搜索
userId	string	搜索特定用户创建的文档
dateFilter	string	按时间筛选，可选值：day, week, month, year
statusFilter	array	按状态筛选

cURL请求

curl -X POST https://your-outline-instance.com/api/documents.search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "query": "API集成",
    "collectionId": "collection-uuid",
    "dateFilter": "month",
    "statusFilter": ["published"]
  }'

搜索流程

flowchart LR
    A[接收搜索请求] --> B[解析查询参数]
    B --> C[构建搜索索引查询]
    C --> D[执行全文搜索]
    D --> E[应用筛选条件]
    E --> F[排序并返回结果]

⚠️ 注意事项：搜索接口有频率限制，每分钟最多100次调用，超过限制将返回429状态码。

3.3 版本控制

3.3.1 文档版本管理

Outline API支持文档版本控制，可以查看历史版本和恢复到之前的版本：

获取文档版本列表

curl -X POST https://your-outline-instance.com/api/revisions.list \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "documentId": "document-uuid"
  }'

恢复到历史版本

curl -X POST https://your-outline-instance.com/api/documents.restore \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "id": "document-uuid",
    "revisionId": "revision-uuid"
  }'

四、实践案例

4.1 集成示例：文档管理系统

场景描述：构建一个自定义文档管理系统，实现文档的创建、查询、更新和权限管理功能。

实现步骤：

1. 认证集成

   • 实现登录功能获取JWT令牌
   • 建立令牌刷新机制，处理令牌过期问题

2. 文档列表展示

   • 调用documents.list接口获取文档列表
   • 实现分页和筛选功能
   • 展示文档基本信息和权限状态

3. 文档编辑功能

   • 调用documents.info获取文档详情
   • 使用ProseMirror编辑器实现内容编辑
   • 通过documents.update保存修改

4. 权限管理

   • 调用documents.add_user和documents.add_group设置权限
   • 实现权限可视化界面

数据流转过程

flowchart TD
    A[用户登录] --> B[获取JWT令牌]
    B --> C[获取文档列表]
    C --> D[展示文档列表]
    D --> E{选择文档}
    E --> F[查看文档详情]
    E --> G[创建新文档]
    F --> H[编辑文档内容]
    H --> I[更新文档]
    G --> J[填写文档信息]
    J --> K[保存新文档]

4.2 性能优化建议

4.2.1 缓存策略

• 实现客户端缓存：对不常变化的资源（如文档列表、用户信息）进行本地缓存
• 利用ETag：通过响应头中的ETag实现条件请求，减少不必要的数据传输
• 批量请求：使用批量接口减少API调用次数

4.2.2 批量操作技巧

• 批量获取：使用documents.batchInfo一次获取多个文档详情
• 分页优化：合理设置分页大小，平衡请求次数和数据量
• 异步处理：对于耗时操作（如文档导入），使用异步任务并轮询结果

4.3 版本迁移指南

4.3.1 API版本差异

Outline API目前有v1和v2两个版本，主要差异：

版本	特点	适用场景
v1	基础功能，响应格式简单	简单集成，兼容性要求高
v2	增强功能，支持更多参数和更丰富的响应	新开发项目，需要高级功能

4.3.2 迁移步骤

1. 评估依赖：分析当前使用的API接口，确定需要更新的部分
2. 增量迁移：先在非关键功能中使用v2接口，验证兼容性
3. 处理响应差异：调整代码以适应v2接口的响应格式
4. 测试验证：全面测试确保迁移后功能正常

💡 迁移提示：可以通过apiVersion参数指定使用的API版本，便于逐步迁移。