跳转到主要内容

Getting Started

开始使用

本文档说明如何调用本产品的 HTTP API。系统 BookStack 平台 API 请另见 /api/docs（与本书无关）。

Base URL

所有路径均相对于下方根地址（请改成你的环境）。

生产 
https://api.example.com
沙箱（可选） 
https://api.sandbox.example.com

鉴权

在请求头携带访问令牌（按你的实际方案改文案）：

Header 
Authorization: Bearer <token>
curl 
curl -sS 'https://api.example.com/v1/widgets/wdg_42' \
  -H 'Authorization: Bearer YOUR_TOKEN'

请求格式

写操作请设置 Content-Type: application/json。各端点接受的字段见对应页的参数表。

错误处理

成功一般为 200 / 201 / 204。失败返回 4xx/5xx，正文建议统一为：

{
  "error": {
    "code": 401,
    "message": "Unauthorized"
  }
}
HTTP含义说明
400 参数错误 校验失败；见 message
401 未鉴权 缺少或无效 Token
403 无权限 Token 有效但无权访问资源
404 未找到 资源不存在
429 限流 见下方 Rate Limits

限流

默认示例：每用户每分钟 180 次（按你的网关改）。触发时返回 429。

建议客户端行为 
# 尊重 Retry-After（若下发）
# 退避重试；避免突发打满配额

本书约定

  • 一端点一页；章 = 资源。
  • 页内使用 .cb-api-* 类；方法徽章为甲·浅底方章。
  • 试调仅提供 curl / fetch 静态示例，无在线调试器。