开始使用

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

Base URL

https://api.example.com

https://api.sandbox.example.com

鉴权

Authorization: Bearer <token>

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"
  }
}

限流

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

# 尊重 Retry-After（若下发）
# 退避重试；避免突发打满配额

本书约定

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