Outline API 开发者指南：从集成到实战的完整路径

在现代软件开发中，API集成已成为连接不同系统的核心桥梁。Outline作为一款协作式团队知识库，其精心设计的RESTful接口为开发者提供了灵活的集成能力。本指南将深入探讨Outline API的接口设计原则与开发实践，帮助开发团队快速实现与知识库的无缝对接，构建自定义工作流和扩展功能。

一、API基础规范

1.1 接口通信标准

Outline API采用RESTful设计风格，所有接口均通过HTTP协议进行通信，基础URL为/api。接口交互采用JSON格式进行数据交换，认证方式基于JWT（JSON Web Token）机制。每个请求需在HTTP头部包含有效的认证信息，格式为Authorization: Bearer YOUR_JWT_TOKEN。

接口响应遵循统一的结构，包含三个核心部分：

• pagination：分页信息，仅在返回列表数据时出现
• data：接口返回的具体业务数据
• policies：当前用户对资源的操作权限说明

1.2 错误处理机制

API使用标准HTTP状态码表示请求处理结果：

• 2xx系列：请求成功处理
• 400：请求参数错误
• 401：未授权访问
• 403：权限不足
• 404：资源不存在
• 422：数据验证失败
• 500：服务器内部错误

错误响应包含详细的错误信息：

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

1.3 请求频率限制

为保障系统稳定性，API实施以下调用频率限制：

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

超过限制时，接口将返回429状态码。建议在实现时添加请求重试机制，并处理限流响应。

flowchart TD
    A[发起API请求] --> B{是否携带有效Token?}
    B -->|否| C[返回401错误]
    B -->|是| D{请求频率是否超限?}
    D -->|是| E[返回429错误]
    D -->|否| F{参数是否有效?}
    F -->|否| G[返回422错误]
    F -->|是| H[处理请求并返回结果]

二、核心功能模块

2.1 文档管理

功能概述

文档管理是Outline API的核心功能，提供文档的创建、查询、更新和删除等完整生命周期管理能力。

应用场景

适用于构建自定义文档管理界面、批量导入/导出文档、与其他系统同步内容等场景。

调用示例

创建文档（Python）

import requests
import json

def create_document(token, title, content, collection_id):
    url = "/api/documents.create"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    data = {
        "title": title,
        "text": content,
        "collectionId": collection_id,
        "publish": True
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

# 使用示例
token = "your_jwt_token"
new_doc = create_document(token, "API使用指南", "这是通过API创建的文档内容", "collection_uuid")
print(f"创建的文档ID: {new_doc['data']['id']}")

获取文档列表（Python）

def get_documents(token, collection_id, sort="updatedAt", direction="DESC"):
    url = "/api/documents.list"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    data = {
        "sort": sort,
        "direction": direction,
        "collectionId": collection_id
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

注意事项

• 参数说明：
  • title: 字符串（必选）- 文档标题
  • text: 字符串（必选）- 文档内容，使用ProseMirror JSON格式
  • collectionId: 字符串（必选）- 文档所属集合ID
  • publish: 布尔值（可选）- 是否发布文档，默认为false
  • parentDocumentId: 字符串（可选）- 父文档ID，用于创建子文档
• 创建文档时如未指定ID，系统将自动生成UUID
• 文档内容需使用ProseMirror JSON格式，可通过Outline编辑器导出获取格式示例

flowchart TD
    A[创建文档] --> B[验证权限]
    B --> C[验证参数]
    C --> D[生成文档ID]
    D --> E[保存文档内容]
    E --> F[创建文档元数据]
    F --> G[返回文档信息]

2.2 文档状态管理

功能概述

提供文档的归档、恢复、发布和取消发布等状态管理操作，满足文档生命周期管理需求。

应用场景

适用于实现文档版本控制、内容审核流程、过期内容管理等业务场景。

调用示例

归档文档（Python）

def archive_document(token, document_id):
    url = "/api/documents.archive"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    data = {
        "id": document_id
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

恢复文档（Python）

def restore_document(token, document_id, collection_id=None, revision_id=None):
    url = "/api/documents.restore"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    data = {
        "id": document_id
    }
    
    if collection_id:
        data["collectionId"] = collection_id
    if revision_id:
        data["revisionId"] = revision_id
        
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

注意事项

• 参数说明：
  • id: 字符串（必选）- 文档ID
  • collectionId: 字符串（可选）- 恢复文档到的目标集合ID
  • revisionId: 字符串（可选）- 要恢复到的历史版本ID
• 归档操作不会删除文档，而是将其标记为归档状态
• 恢复操作可将文档从归档或删除状态恢复，并可指定恢复到特定版本

flowchart TD
    A[文档状态操作] --> B{操作类型}
    B -->|归档| C[设置archivedAt时间戳]
    B -->|恢复| D[清除archivedAt和deletedAt时间戳]
    B -->|发布| E[设置publishedAt时间戳]
    B -->|取消发布| F[清除publishedAt时间戳]
    C --> G[返回操作结果]
    D --> G
    E --> G
    F --> G

2.3 文档操作

功能概述

提供文档的复制、移动、导出和导入等操作，支持文档的批量管理和格式转换。

应用场景

适用于创建文档模板、重组文档结构、数据迁移和备份等场景。

调用示例

复制文档（Python）

def duplicate_document(token, document_id, new_title, collection_id=None):
    url = "/api/documents.duplicate"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    data = {
        "id": document_id,
        "title": new_title,
        "recursive": False,
        "publish": False
    }
    
    if collection_id:
        data["collectionId"] = collection_id
        
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

导出文档（Python）

def export_document(token, document_id, export_format="text/markdown"):
    url = "/api/documents.export"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}",
        "Accept": export_format
    }
    data = {
        "id": document_id
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(data))
    
    if response.status_code == 200:
        return {
            "status": "success",
            "content": response.text,
            "format": export_format
        }
    else:
        return {"status": "error", "message": response.json()}

注意事项

• 参数说明：
  • id: 字符串（必选）- 源文档ID
  • title: 字符串（必选）- 新文档标题
  • recursive: 布尔值（可选）- 是否递归复制子文档，默认为false
  • publish: 布尔值（可选）- 是否发布新文档，默认为false
• 导出支持的格式：
  • text/html: HTML格式
  • text/markdown: Markdown格式
  • application/pdf: PDF格式（仅企业版支持）
• 导入操作需要使用multipart/form-data格式提交文件

flowchart TD
    A[文档操作] --> B{操作类型}
    B -->|复制| C[创建新文档记录]
    C --> D[复制文档内容]
    D --> E[返回新文档ID]
    B -->|移动| F[更新文档集合和父文档引用]
    F --> G[重新排序相关文档]
    G --> E
    B -->|导出| H[转换文档格式]
    H --> I[返回文件内容]

三、扩展能力

3.1 文档搜索

功能概述

提供强大的文档搜索能力，支持标题搜索和内容搜索，可按多种条件筛选结果。

应用场景

适用于构建自定义搜索界面、实现智能内容推荐、创建知识图谱等场景。

调用示例

搜索文档内容（Python）

def search_documents(token, query, collection_id=None, date_filter=None):
    url = "/api/documents.search"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    data = {
        "query": query,
        "statusFilter": ["published"],
        "snippetMinWords": 20,
        "snippetMaxWords": 30
    }
    
    if collection_id:
        data["collectionId"] = collection_id
    if date_filter:
        data["dateFilter"] = date_filter
        
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

注意事项

• 参数说明：
  • query: 字符串（必选）- 搜索关键词
  • collectionId: 字符串（可选）- 限制搜索特定集合
  • dateFilter: 字符串（可选）- 日期筛选，可选值：day, week, month, year
  • statusFilter: 数组（可选）- 状态筛选，可选值：published, draft, archived
• 搜索接口有更严格的频率限制（每分钟100次）
• 搜索结果包含匹配内容的摘要片段，可通过snippetMinWords和snippetMaxWords控制摘要长度

flowchart TD
    A[搜索请求] --> B[验证权限]
    B --> C[解析搜索参数]
    C --> D[构建搜索查询]
    D --> E[执行索引搜索]
    E --> F[生成结果摘要]
    F --> G[应用权限过滤]
    G --> H[返回分页结果]

3.2 权限管理

功能概述

提供细粒度的文档权限管理，支持为用户和组分配不同级别的访问权限。

应用场景

适用于实现团队协作空间、客户文档门户、内容审核流程等需要权限控制的场景。

调用示例

添加用户权限（Python）

def add_document_permission(token, document_id, user_id, permission):
    url = "/api/documents.add_user"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
    data = {
        "id": document_id,
        "userId": user_id,
        "permission": permission
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

注意事项

• 参数说明：
  • id: 字符串（必选）- 文档ID
  • userId: 字符串（必选）- 用户ID
  • groupId: 字符串（必选）- 组ID（用于组权限操作）
  • permission: 字符串（必选）- 权限级别，可选值：read, read_write, admin
• 权限级别说明：
  • read: 仅查看权限
  • read_write: 查看和编辑权限
  • admin: 完全管理权限，包括权限分配
• 文档权限会继承集合权限，明确设置的文档权限会覆盖继承的权限

flowchart TD
    A[权限操作] --> B{操作类型}
    B -->|添加用户权限| C[验证当前用户权限]
    B -->|添加组权限| C
    B -->|移除权限| C
    C --> D{是否有权限?}
    D -->|否| E[返回403错误]
    D -->|是| F[更新权限记录]
    F --> G[返回操作结果]

四、最佳实践

4.1 认证流程优化

建议实现JWT令牌的自动刷新机制，避免频繁要求用户重新登录：

import time
from datetime import datetime

class AuthManager:
    def __init__(self, auth_endpoint):
        self.auth_endpoint = auth_endpoint
        self.token = None
        self.expires_at = 0
        
    def get_token(self, username, password):
        # 获取新令牌
        response = requests.post(self.auth_endpoint, data={
            "username": username,
            "password": password
        })
        data = response.json()
        self.token = data["token"]
        self.expires_at = time.time() + data["expiresIn"] - 60  # 提前60秒刷新
        return self.token
        
    def get_valid_token(self):
        # 检查令牌是否即将过期
        if time.time() >= self.expires_at:
            # 实现令牌刷新逻辑
            self.refresh_token()
        return self.token
        
    def refresh_token(self):
        # 实现令牌刷新
        # ...

4.2 批量操作处理

对于大量文档操作，建议实现分批处理和错误重试机制：

def batch_operation(operation_func, items, batch_size=10):
    results = []
    errors = []
    
    # 将项目分批次处理
    for i in range(0, len(items), batch_size):
        batch = items[i:i+batch_size]
        for item in batch:
            try:
                result = operation_func(item)
                results.append({
                    "item": item,
                    "success": True,
                    "result": result
                })
            except Exception as e:
                errors.append({
                    "item": item,
                    "success": False,
                    "error": str(e)
                })
                
        # 避免请求过于频繁
        time.sleep(1)
        
    return {
        "total": len(items),
        "success": len(results),
        "failed": len(errors),
        "results": results,
        "errors": errors
    }

4.3 错误处理策略

实现全面的错误处理机制，提高应用的健壮性：

def api_request_with_retry(url, method="post", max_retries=3, **kwargs):
    retry_count = 0
    backoff_factor = 0.3  # 指数退避因子
    
    while retry_count < max_retries:
        try:
            if method.lower() == "post":
                response = requests.post(url, **kwargs)
            elif method.lower() == "get":
                response = requests.get(url, **kwargs)
            else:
                raise ValueError(f"Unsupported HTTP method: {method}")
                
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.RequestException as e:
            retry_count += 1
            if retry_count >= max_retries:
                raise
                
            # 计算退避时间
            sleep_time = backoff_factor * (2 **(retry_count - 1))
            time.sleep(sleep_time)
            
            # 处理特定错误
            if response.status_code == 429:
                # 处理限流，使用响应中的Retry-After头
                retry_after = response.headers.get("Retry-After", sleep_time)
                time.sleep(int(retry_after))

五、常见问题解答

Q1: 如何获取API访问令牌？

A1: API访问令牌需要通过用户认证获取。可以使用现有用户凭据调用认证接口获取JWT令牌，令牌有效期通常为24小时。对于服务集成，建议创建专用的服务账户并为其分配适当的权限。

Q2: 文档内容的ProseMirror JSON格式如何生成？

A2: ProseMirror JSON格式是Outline内部使用的文档表示格式。可以通过两种方式获取：一是使用Outline编辑器创建示例文档，然后通过documents.info接口获取其内容；二是参考ProseMirror官方文档构建自定义生成器。对于简单文本内容，可以使用简化格式：{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"文档内容"}]}]}。

Q3: 如何处理API调用频率限制？

A3: 实现请求限流处理机制：1) 监控响应头中的X-RateLimit-Remaining值；2) 使用指数退避算法处理429错误；3) 实现请求队列和批处理，避免短时间内发送大量请求；4) 对不同类型的接口（普通接口和搜索接口）采用不同的限流策略。

Q4: 能否通过API创建和管理集合？

A4: 是的，Outline API提供了完整的集合管理接口，包括collections.create、collections.update、collections.delete等。集合管理的权限控制与文档类似，需要管理员权限才能执行创建和删除操作。

Q5: API是否支持实时协作功能？

A5: Outline的实时协作功能基于WebSocket实现，目前没有通过REST API直接暴露。对于需要实时功能的集成，可以考虑使用Outline的共享编辑功能，或通过WebHook接收文档变更通知，实现准实时的数据同步。