Files
MySpace/docs/api.md

7.6 KiB
Raw Permalink Blame History

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 导出已发布的博客与书签快照