📢 接口更新声明 · 2025 年 8 月 5日

---

为提升接口一致性与功能完备性，`Baklib` 已对页面内容相关接口做出以下更新：

---

### 🔁 1. 页面详情查询接口区分 `id` 与 `full_path`

* **通过 ID 查询页面详情（保留原接口）**
  `GET /v1/sites/{site_id}/pages/{page_id}`

* **通过 full\_path 查询页面详情（新接口，之前通过/v1/sites/{site_id}/pages/{page_id}传递full_path查询废弃）**
  `GET /v1/sites/{site_id}/pages/by_path/{full_path}`
  ⚠️ `full_path` 需进行 URL 编码（如 `encodeURIComponent`）以避免路由冲突。

---

### ✏️ 2. 页面草稿查询接口新增

* **通过 ID 获取草稿内容：**
  `GET /v1/sites/{site_id}/pages/{page_id}/draft`

* **通过 full\_path 获取草稿内容：**
  `GET /v1/sites/{site_id}/pages/by_path/{full_path}/draft`

---

### 🕓 3. 页面版本内容接口新增

#### ✅ 支持通过 ID 与 full\_path 两种路径访问页面版本信息：

| 操作     | 通过 page\_id 路径                                                     | 通过 full\_path 路径                                                             |
| ------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| 获取版本列表 | `GET /v1/sites/{site_id}/pages/{page_id}/versions`                 | `GET /v1/sites/{site_id}/pages/by_path/{full_path}/versions`                 |
| 获取单个版本 | `GET /v1/sites/{site_id}/pages/{page_id}/versions/{version_id}`    | `GET /v1/sites/{site_id}/pages/by_path/{full_path}/versions/{version_id}`    |
| 创建版本   | `POST /v1/sites/{site_id}/pages/{page_id}/versions`                | `POST /v1/sites/{site_id}/pages/by_path/{full_path}/versions`                |
| 更新版本   | `PUT /v1/sites/{site_id}/pages/{page_id}/versions/{version_id}`    | `PUT /v1/sites/{site_id}/pages/by_path/{full_path}/versions/{version_id}`    |
| 删除版本   | `DELETE /v1/sites/{site_id}/pages/{page_id}/versions/{version_id}` | `DELETE /v1/sites/{site_id}/pages/by_path/{full_path}/versions/{version_id}` |

> ⚠️ 所有通过 full\_path 查询的接口都要求将full_path转义编码。

---

### 🗑 4. 页面列表默认不返回已删除数据

* **获取页面列表（默认仅返回未删除页面）：**
  `GET /v1/sites/{site_id}/pages`

* **如需获取回收站中的已删除页面，请传入参数：**
  `GET /v1/sites/{site_id}/pages?deleted=true`

---

### ✅ 总结更新内容一览

| 功能模块     | 说明/变更                                                         |
| -------- | ------------------------------------------------------------- |
| 页面详情查询   | 区分 ID 与 full\_path 查询方式，full\_path 新增专用路径                     |
| 页面草稿接口   | 新增通过 ID 或 full\_path 获取草稿内容的接口                                |
| 页面版本接口   | **新增完整的版本内容 CRUD 接口**，支持通过 ID 与 full\_path 路径访问               |
| 页面列表行为调整 | 默认不返回删除页面，如需获取回收站数据请添加 `deleted=true` 查询参数                    |
| URL 编码提醒 | 所有涉及 full\_path 的接口必须对路径进行 URL 编码（如使用 `encodeURIComponent()`） |

---

如对更新内容有任何疑问，请联系技术支持。建议所有接入方及时适配新的接口路径，并根据需要对 `full_path` 做 URL 编码处理，确保兼容性与稳定性。

---