20 lines
687 B
Markdown
20 lines
687 B
Markdown
|
# API 设计原则
|
|||
|
|
|
|||
|
|
- REST 风格 + JSON
|
|||
|
|
- 大多数接口使用错误结构：`{"error":"code","message":"..."}`
|
|||
|
|
- 少数接口直接返回 `{"error":"..."}`
|
|||
|
|
- 默认以会话 token 作为认证方式
|
|||
|
|
|
|||
|
|
## 基础路径
|
|||
|
|
|
|||
|
|
- 健康检查：`GET /healthz`
|
|||
|
|
- 用户 API：`/api/auth/*`
|
|||
|
|
- Agent API：`/api/agent/v1/*`
|
|||
|
|
|
|||
|
|
## 认证方式
|
|||
|
|
|
|||
|
|
- 会话 token：`Authorization: Bearer <session-token>` 或 `xc_session` Cookie
|
|||
|
|
- JWT（可选）：启用 `auth.enable` 后，对 `/api/auth/*` 保护路由增加 JWT 校验
|
|||
|
|
|
|||
|
|
> 注意：当前实现中，大部分保护路由仍依赖会话 token。若开启 JWT 中间件，需确保请求同时满足会话逻辑（详见 `api/auth.md` 的说明）。
|