# API 设计 所有业务接口使用 /api/v1,JSON 请求及响应。受保护接口通过 Authorization Bearer 接收短期会话令牌。错误结构为 `{"error":{"code":"…","message":"…"}}`。Web 与桌面端各自持有会话。服务端只保存令牌摘要。 | 方法 | 路径 | 请求与响应 | |---|---|---| | GET | /healthz、/readyz | 分别检查进程和 PostgreSQL、Redis | | POST | /api/v1/auth/challenge | 返回 2 分钟单次使用的 challenge | | POST | /api/v1/auth/register | 接收 username、password、deviceName、platform、publicKey、challenge、signature,返回 201 和 token、user、device | | POST | /api/v1/auth/login | 同上,返回 200 | | POST | /api/v1/auth/logout | 使当前会话失效,返回 204 | | GET | /api/v1/me | 返回账号和当前设备 | | GET | /api/v1/devices | 返回当前账号的设备列表,signedIn 表示有未过期会话,lastActiveAt 来自登录与 WebSocket 心跳 | | DELETE | /api/v1/devices/{id} | 撤销指定设备和其全部会话,返回 204 | | POST | /api/v1/realtime/ticket | 返回 30 秒单次 WebSocket 票据 | | GET | /api/v1/realtime | 通过子协议 xhchat.v1 和 ticket.票据升级,服务器选择 xhchat.v1,连接建立后发送 ready 事件 | | GET | /api/v1/contacts | 返回好友、来往申请和当前账号的黑名单 | | GET | /api/v1/contacts/search?username= | 按完整用户名查找,返回可见的联系人状态 | | POST | /api/v1/contacts/{id} | 请求体包含 action,可选 alias 和 category,成功返回 204 | 用户名为 3–32 位 ASCII 字母、数字或下划线,忽略大小写。密码最少 12 个 Unicode 字符,最多 256 字节。platform 为 web 或 windows。公钥、签名和 challenge 使用无填充 Base64URL。设备使用 Ed25519 签名 UTF-8 字符串 `XHChat device authentication v1\n` 后紧接 challenge。该签名仅用于证明基础设备密钥持有权。 联系人操作包含 request、accept、reject、cancel、delete、block、unblock 和 preferences。变更后 WebSocket 发送 contacts_changed,客户端重新获取授权后的列表。 下一阶段接口为 /conversations、/conversations/{id}/envelopes、/sync、/attachments、/key-packages。消息接口接受版本化协议密文、目标会话和幂等 ID。WebSocket 发出同步提示,客户端按持久游标补拉。后续加入 /groups、/calls、/posts、/backups、/push 与独立的管理接口。