API 参考

基础 URL

所有接口都通过单一的、带版本号的基础路径提供。v1 已稳定，且不会发生破坏性变更。

/api/v1

身份验证

请求通过在登录时签发的短期访问令牌进行身份验证，该令牌以 HTTP-only cookie 的形式发送。过期的令牌会自动刷新。

响应格式

每个响应都使用相同的信封结构。成功的响应会携带 data 数据（列表还会携带 meta）；错误则携带稳定的 code 和一条便于阅读的 message。

{
  "success": true,
  "message": "OK",
  "data": { },
  "meta": { "page": 1, "pageSize": 20, "total": 42 }
}

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "The request could not be processed."
}

约定

• 分页?page=1&pageSize=20
• 过滤?filter[status]=active
• 排序?sort=createdAt:desc

常用接口

这只是一个具有代表性的子集。完整且始终保持最新的参考文档将随公开 API 一同发布。