企业官网建设流程全解析

Hackpad API使用手册：开发者必备的完整参考

【免费下载链接】hackpadHackpad is a web-based realtime wiki.项目地址: https://gitcode.com/gh_mirrors/ha/hackpad

Hackpad是一款基于Web的实时协作文档工具，其强大的API功能允许开发者轻松集成实时编辑、内容管理和团队协作能力到自己的应用中。本手册将详细介绍Hackpad API的核心功能、快速入门步骤以及常用接口的使用方法，帮助开发者快速上手并充分利用Hackpad的协作特性。

快速入门：Hackpad API基础

准备工作

1. 获取API访问权限

   • 登录Hackpad账户，在个人设置中生成API令牌（位于pro/account_settings_control.js中管理）
   • 令牌格式示例：HACKPAD_API_TOKEN = 4（定义于etherpad/src/etherpad/pro/pro_tokens.js）

2. API请求格式

   • 基础URL：/api/1.0/
   • 认证方式：在请求头中包含Authorization: Bearer {token}
   • 响应格式：JSON

首个API调用示例

创建新文档的简单请求：

POST /api/1.0/pad/create Content-Type: text/plain 这是通过API创建的第一个Hackpad文档！

成功响应：

{ "padId": "randomUniquePadId", "globalPadId": "g.1234567890abcdef" }

核心API功能详解

文档管理接口

创建文档

• 接口：POST /api/1.0/pad/create
• 功能：创建新的空白文档
• 参数：请求体包含初始内容
• 返回：新文档ID和全局ID

获取文档内容

• 接口：GET /api/1.0/pad/{padId}/content.{format}
• 支持格式：html、md（Markdown）、txt、native
• 示例：GET /api/1.0/pad/example-pad/content.md

更新文档内容

• 接口：POST /api/1.0/pad/{padId}/content
• 内容类型：支持text/html、text/x-web-markdown和text/plain
• 代码实现：etherpad/src/etherpad/control/api_v1_control.js中的render_v1_set_content_post函数

文档版本控制

获取修订历史

• 接口：GET /api/1.0/pad/{padId}/revisions
• 功能：获取文档的编辑历史记录，包括作者、时间戳和内容差异
• 响应示例：

[ { "startRev": 0, "endRev": 1, "timestamp": 1620000000, "authors": ["John Doe"], "htmlDiff": "<ins>新增内容</ins>" } ]

回滚到历史版本

• 接口：POST /api/1.0/pad/{padId}/revert-to/{revisionId}
• 参数：revisionId- 目标版本号
• 权限：需要文档编辑权限

用户与权限管理

获取用户信息

• 接口：GET /api/1.0/user/{encryptedUserId}/profile
• 功能：获取用户的基本信息，包括姓名和头像
• 响应示例：

{ "profile": { "fullName": "Jane Smith", "photoUrl": "https://example.com/avatar.jpg" } }

管理文档权限

• 接口：GET /api/1.0/pad/{padId}/permissions
• 功能：获取文档的访问权限列表，包括创建者和授权用户
• 权限修改：POST /api/1.0/pad/{padId}/revoke-access/{email}可撤销用户访问权

高级应用场景

实时协作集成

Hackpad API支持通过WebSocket实现实时协作功能：

• 监听文档变更：socket.io客户端连接（etherpad/src/static/js/socket.io.js）
• 接收变更事件：文档编辑、用户加入/离开等实时通知

批量操作与自动化

1. 批量导出文档

   • 使用GET /api/1.0/pad/{padId}/export-info获取完整文档信息
   • 支持导出为多种格式，适合备份或迁移

2. 自动化工作流

   • 结合GET /api/1.0/edited-since/{timestamp}监控文档更新
   • 实现自动同步到其他系统（如版本控制系统、CMS等）

常见问题与解决方案

认证失败

• 检查API令牌是否有效：pro_oauth.getAuthorizedRequestApiAccount()（位于api_v1_control.js）
• 确保请求头中正确设置了Authorization字段

文档访问权限问题

• 验证用户是否在文档的权限列表中：_getPadPermissions函数（位于api_v1_control.js第379行）
• 检查文档的 guestPolicy 设置，确认是否允许外部访问

处理大文档

• 使用分块获取修订历史：设置limit参数控制返回记录数
• 增量同步：通过edited-since接口只获取更新的文档

API参考资源

接口列表

完整API端点定义在etherpad/src/etherpad/control/api_v1_control.js中，主要包括：

错误码参考

• 401: 认证失败或权限不足
• 404: 文档不存在
• 400: 请求参数错误

通过本手册，开发者可以快速掌握Hackpad API的使用方法，将实时协作能力无缝集成到自己的应用中。无论是构建团队协作工具、内容管理系统还是自动化工作流，Hackpad API都能提供强大而灵活的支持。

【免费下载链接】hackpadHackpad is a web-based realtime wiki.项目地址: https://gitcode.com/gh_mirrors/ha/hackpad