HTTP API 规范

业务 API 使用 /api/v1 前缀和 JSON。健康检查是运维接口，不加版本前缀。

身份 API

POST /api/v1/auth/register

请求：

{
  "email": "user@example.com",
  "password": "correct horse 电池 staple",
  "display_name": "Shawn"
}

成功时返回 201 Created、Profile，并设置登录 Cookie：

{
  "id": "019c9122-e715-7ea3-89d4-f1f046e365f4",
  "email": "user@example.com",
  "display_name": "Shawn",
  "created_at": "2026-07-24T12:00:00Z"
}

邮箱保存前去除首尾空白并转为小写；显示名称去除首尾空白。注册成功即登录。

POST /api/v1/auth/login

请求：

{
  "email": "user@example.com",
  "password": "correct horse 电池 staple"
}

成功时返回 200 OK 和 Profile，并轮换当前 Session ID。邮箱不存在与密码错误 统一返回 401 INVALID_CREDENTIALS。

POST /api/v1/auth/logout

删除当前设备 Session、清除 Cookie，返回 204 No Content。其他设备的 Session 不受影响；未登录时重复退出仍返回 204。

GET /api/v1/profile

返回当前用户的只读 Profile。无有效 Session、Session 闲置过期或达到绝对期限 时返回 401 AUTHENTICATION_REQUIRED。

输入规则

• 邮箱去除首尾空白后转小写，全局唯一，最长 254 个字符。
• 显示名称去除首尾空白，长度 1–80 个 Unicode 字符，不允许控制字符。
• 密码长度 15–128 个 Unicode 字符，允许空格、符号和 Unicode，不静默截断。
• 不可解析的 JSON 返回 400 INVALID_REQUEST。
• 字段校验失败返回 422 VALIDATION_ERROR，具体字段位于 error.fields。

Cookie

Session Cookie 名为 rustloom_session，属性为 HttpOnly、SameSite=Lax 和 Path=/，不设置 Domain。开发环境允许 Secure=false；HTTPS 生产环境必须 设置 SESSION_COOKIE_SECURE=true。

使用 curl 保留 Cookie：

curl -i -c .cookies \
  -H 'content-type: application/json' \
  -d '{"email":"user@example.com","password":"correct horse 电池 staple","display_name":"Shawn"}' \
  http://127.0.0.1:3000/api/v1/auth/register

curl -i -b .cookies http://127.0.0.1:3000/api/v1/profile

.cookies 可能包含有效登录凭据，只能作为本地临时文件，不得提交。

运维接口

GET /health

只检查 HTTP 进程是否运行，不访问依赖：

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8

ok

GET /ready

执行轻量 PostgreSQL 查询。成功返回 200：

{"status":"ready"}

数据库不可用时返回 503 DATABASE_UNAVAILABLE。

错误格式

{
  "error": {
    "code": "STABLE_MACHINE_CODE",
    "message": "safe public message"
  }
}

code 是稳定、可测试的机器标识。客户端应结合 HTTP 状态处理错误，不依赖 message 文本。