Files
MySpace/docs/api.md
T

78 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API(第一阶段 + 博客管理 + 导航书签 + 公开博客)
所有路径以 `/api/v1` 开头,业务 API 需登录 Cookie;不使用浏览器持久化 token。除 GET 外需 `X-CSRF-TOKEN` 请求头,值从 `/auth/csrf` 的 `token` 字段取得(响应也给出 `headerName`)。登录和退出后重新请求 token。
| 方法 | 路径 | 请求/结果 |
|---|---|---|
| GET | /auth/csrf | `{token,headerName}`,匿名可访问 |
| POST | /auth/login | form-urlencoded `username,password`;成功 200,失败 401 |
| GET | /auth/me | `{username}` |
| POST | /auth/logout | 成功 204,失效会话 |
| GET | /dashboard | `{notes,starred,assets,bookmarks,storageBytes,recentNotes}` |
| GET | /notes | `q, category, starred, offset`;数组,每页最多 100 |
| POST | /notes | `{title,body,category,tag,star,version:0}`;201 + 完整记录 |
| GET | /notes/categories | 返回已保存的笔记分类名称数组 |
| POST | /notes/categories | `{name}`;创建分类并返回 `{name}`,重名返回 409 |
| GET | /notes/categories/usage | 返回分类名称和笔记数 `{name,noteCount}` |
| DELETE | /notes/categories | `name` 指定分类,`replacement` 指定迁移目标。空分类可直接删除。有笔记时需提供另一个分类。至少保留一个分类,成功返回 204 |
| GET | /notes/{uuid} | 完整记录 |
| PUT | /notes/{uuid} | 同创建字段,version 必须是读取时版本;更新返回 version+1;冲突 409 |
| DELETE | /notes/{uuid} | 204,移入回收站;不存在返回 404 |
| GET | /assets | `q,type=all/image/file,offset`;数组,每页最多 100 |
| POST | /assets | multipart 字段 `file`,单文件 1 字节至 15 MB;201 |
| GET | /assets/{uuid}/content | PNG/JPEG/GIF 内联,其他附件;`download=true` 强制下载 |
| DELETE | /assets/{uuid} | 删除磁盘文件与元数据,204 |
| GET | /bookmarks | `q,category,offset`;数组,每页最多 100,按更新时间倒序 |
| POST | /bookmarks | `{title,url,description,category,icon_asset_id,is_public}`;默认私有,图标可选,必须是图床图片;仅接受有效的 http(s) URL;201 + 完整记录 |
| GET | /bookmarks/{uuid} | 完整记录 |
| PUT | /bookmarks/{uuid} | 请求字段与新增一致;更新原记录及公开状态;不存在返回 404 |
| DELETE | /bookmarks/{uuid} | 204,移入回收站;不存在返回 404 |
| GET | /public/bookmarks | 匿名只读;`offset,limit(1–100,默认 50)`;仅展示已同步至公开快照的记录,返回 `{title,url,description,category,icon_asset_id,updated_at}` |
| GET | /public/bookmarks/images/{uuid} | 匿名读取被公开书签选为图标的 PNG/JPEG/GIF;其他图片或未引用图片返回 404 |
| GET | /blogs | `q, status=all/draft/published, offset`;数组,每页最多 100,按更新时间倒序 |
| POST | /blogs | `{title,summary,body,status,version:0,cover_asset_id,category}`;status 为 draft/published;201 + 完整记录 |
| GET | /blogs/{uuid} | 完整记录 |
| PUT | /blogs/{uuid} | 同创建字段,version 必须是读取时版本;更新返回 version+1;冲突 409 |
| DELETE | /blogs/{uuid} | 204,移入回收站;不存在返回 404 |
| GET | /public/blogs | 匿名只读;`offset, limit(1–50,默认 20), q, category`;仅已同步的已发布文章,`{title,summary,slug,updated_at,cover_asset_id,category}`,按更新时间倒序 |
| GET | /public/blogs/rss.xml | 匿名订阅最近 30 篇已同步的文章,返回 RSS 2.0 |
| GET | /public/blogs/categories | 匿名只读;返回已发布文章的分类列表 |
| GET | /public/blogs/{slug} | 匿名只读;仅已同步的已发布文章,额外返回 `body`;草稿或不存在的 slug 均为 404 |
| GET | /public/blogs/{slug}/images/{uuid} | 匿名读取该已发布文章引用的封面或 Markdown 图片;其余情况返回 404 |
笔记字段:id(UUID)、title(1–120 非空)、body(最多 1,000,000 字符)、category(1–60 非空)、tag(0–60)、star、version、created_at、updated_at。
资产字段:id、name、media_type、size(字节)、created_at。时间由数据库产生,使用 timestamptz。
书签字段:id(UUID)、title(1–60 非空)、url(有效 http/https 地址,最多 4096 字符)、description(0–160)、category(1–60 非空)、created_at、updated_at。书签为私有数据;管理页面使用 `target="_blank"` 与 `rel="noopener noreferrer"` 打开网址。
博客字段:id(UUID)、title(1–120 非空)、summary(0–200)、body(最多 1,000,000 字符)、status(draft/published,数据库 CHECK 约束)、slug(唯一)、version、created_at、updated_at。列表不返回数量汇总;前端在本地按状态和关键词筛选(页内搜索与全局搜索都按正文匹配)。
`cover_asset_id` 是可选的图床图片 UUID。提交 `null` 可移除封面。Flyway V4 为已有文章新增该字段,删除对应图床原图时自动清空。
`slug` 由服务端在创建时按标题生成:小写 ASCII 字母数字保留,其余转连字符,最多 80 字符;不含字母(如纯中文或纯数字标题)时用 `article`,再追加 id 前 6 位保证唯一。编辑标题不会改变 slug,已分享的链接保持有效。
公开与私有边界:
- `/public/**` 可匿名访问,是前端 `/blog`、`/blog/<slug>` 页面的唯一数据来源;响应不含 id、version 等内部字段,公开页面请求时使用 `credentials: "omit"`,页面被嵌入或分享时不会带上登录 Cookie。
- 公开接口响应携带 ETag(根据文章版本、封面及当前页文章集合生成),带 `If-None-Match` 的条件请求内容未变时返回 304;公开页面每 30 秒、以及窗口重新获得焦点时做条件请求,文章更新后自动刷新。
- 所有 `/blogs` 管理接口仍需登录和 CSRF。单账户平台,不提供按作者或空间的隔离;公开页面目前可被同一台电脑上的浏览器访问,是否可被互联网访问取决于部署与网络环境。
响应头:所有响应带 `X-Content-Type-Options: nosniff`、`Referrer-Policy: strict-origin-when-cross-origin`、`X-Frame-Options: SAMEORIGIN`。
错误:401 未登录/凭据错误;403 CSRF 不合法;400 输入校验失败(含非法 status 筛选值);404 不存在;409 版本冲突;413 超过上传限制;500 服务失败。控制器业务错误为 `{message}`;安全过滤器错误可能采用 Spring 标准错误格式。前端保留未保存内容并提示错误,不将失败当成功。
## V4 工作区
| 方法 | 路径 | 用途 |
|---|---|---|
| GET、POST | /library/{kind}/folders | 知识库及图床的文件夹列表与新增 |
| GET | /library/{kind}/facets | 知识库及图床的文件夹计数、标签和图床存储统计 |
| GET、POST、PUT | /library/{kind}/categories | 分类列表、新增、改名或迁移后删除 |
| POST | /library/{kind}/batch | 对指定 ID 批量移动、加标签、移入回收站或调整书签顺序 |
| GET | /library/{kind}/trash | 按模块查看已删除记录 |
| POST、DELETE | /library/{kind}/trash/{id} | 恢复或永久删除 |
| GET | /notes/{id}/history | 按笔记分页读取版本列表 |
| GET、POST | /notes/{id}/history/{version} | 预览历史版本或使用当前版本号恢复 |
| GET | /notes/{id}/backlinks | 查找引用当前笔记的双链 |
| GET、PUT | /assets/{id} | 读取和编辑文件名、分类、文件夹、标签、描述 |
| PUT | /bookmarks/{id}/favorite | 修改常用收藏状态 |
| POST | /bookmarks/import | 批量导入并按网址去重,导入项默认私有 |
| GET、POST | /publication | 查看待同步清单或按当前发布版本提交同步 |
| GET | /publication/export | 导出已发布的博客与书签快照 |