BookStack API 入门指南：从认证到高级查询

前言

BookStack 是一款开源的文档管理系统，提供了完善的 REST API 接口，方便开发者进行系统集成和二次开发。本文将全面介绍 BookStack API 的使用方法，帮助开发者快速上手并掌握核心功能。

认证机制

权限准备

要使用 BookStack API，用户必须拥有"Access System API"权限。该权限需要通过角色分配给用户，且API访问的内容权限受限于该用户的其他角色权限。

API Token认证

BookStack 主要采用 API Token 进行认证：

1. 用户登录后，在个人资料编辑页面找到"API Tokens"部分
2. 点击"Create Token"，填写适当的名称和过期日期
3. 系统会生成"Token ID"和"Token Secret"

使用方式是在请求头中添加：

Authorization: Token <token_id>:<token_secret>

示例cURL请求：

curl --request GET \
  --url https://example.com/api/books \
  --header 'Authorization: Token C6mdvEQTGnebsmVn3sFNeeuelGEBjyQp:NOvD3VlzuSVuBPNaf1xWHmy7nIRlaj22'

会话认证

如果用户已通过浏览器登录且拥有API访问权限，系统也会接受现有会话，方便直接在浏览器中测试API端点。

请求格式

支持的Content-Type

BookStack API 支持三种请求数据格式：

1. application/json（推荐）
2. application/x-www-form-urlencoded
3. multipart/form-data

注意：表单格式目前仅适用于POST请求。如需在PUT或DELETE请求中使用表单格式，可通过POST请求并添加"_method"参数来模拟。

复杂数据结构处理

对于嵌套对象或数组等复杂数据结构，非JSON格式请求可以使用方括号表示法：

JSON示例：

{
  "name": "My new item",
  "locked": true,
  "books": [105, 263],
  "tags": [{"name": "Tag Name", "value": "Tag Value"}]
}

等效的x-www-form-urlencoded格式：

name=My new item
locked=1
books[0]=105
books[1]=263
tags[0][name]=Tag Name
tags[0][value]=Tag Value

列表端点使用技巧

基本响应结构

列表端点返回的数据包含两个主要属性：

• data: 数据模型数组
• total: 系统中匹配查询的记录总数

示例响应：

{
  "data": [
    {
      "id": 1,
      "name": "BookStack User Guide",
      "slug": "bookstack-user-guide",
      "description": "This is a general guide on using BookStack on a day-to-day basis.",
      "created_at": "2019-05-05 21:48:46",
      "updated_at": "2019-12-11 20:57:31",
      "created_by": 1,
      "updated_by": 1,
      "image_id": 3
    }
  ],
  "total": 16
}

分页与排序参数

参数	说明	示例
count	指定返回记录数（默认: 15, 最大: 100）	?count=50
offset	指定跳过的记录数（默认: 0）	?offset=100
sort	指定排序字段和方向（+升序/-降序）	?sort=-created_at

高级过滤功能

通过filter[<field>]参数可以实现复杂查询：

操作符	说明	示例
eq	等于	?filter[id]=5
ne	不等于	?filter[id:ne]=5
gt	大于	?filter[created_at:gt]=2020-01-01
lt	小于	?filter[created_at:lt]=2020-01-01
like	模糊匹配（%为通配符）	?filter[name:like]=%cat%

错误处理与安全

错误响应格式

错误响应遵循统一格式：

{
  "error": {
    "code": 401,
    "message": "No authorization token found on the request"
  }
}

速率限制

API默认限制为每分钟180次请求，可通过环境变量调整：

API_REQUESTS_PER_MIN=180

超过限制会返回429错误。

内容安全建议

• 用户提供的内容（如HTML或Markdown）可能包含不安全代码
• 系统会进行基本过滤，但不能完全保证安全
• 建议在外部展示时使用CSP或禁用JavaScript

扩展选项

除了REST API，BookStack还提供其他扩展方式：

1. Webhooks：系统事件触发HTTP POST调用
2. 视觉主题系统：覆盖视图、翻译和图标
3. 逻辑主题系统：扩展后端功能

通过本文介绍的内容，开发者可以充分利用BookStack API实现各种集成需求，从简单的数据查询到复杂的系统集成。建议在实际开发前充分测试API行为，并根据业务需求设计适当的错误处理和安全措施。