通用约定

响应结构

成功时 ok 为 true,业务数据在与接口对应的字段里(user / sites / items 等)。失败时 ok 为 false,并带一条中文 message。

// 成功
{"ok": true, "sites": [ ... ], "total": 13}

// 失败
{"ok": false, "message": "网站不存在"}

不要只看 HTTP 状态码。少数接口在业务失败时仍返回 200,但 ok 为 false。判断成功的正确顺序是:先看 ok,再看状态码。

# 正确的判定
r = requests.get(url, headers=H)
d = r.json()
if not d.get("ok"):
    raise RuntimeError(d.get("message"))

# 错误的判定 —— 会把 200 + ok:false 当成功
if r.status_code == 200:
    ...

分页

返回列表的接口支持 page(从 1 开始)与 page_size,响应里回显这两个值并带 total。

page_size 有上限。传入超限值会被截断到上限而不是报错 —— 请按响应里回显的 page_size 计算总页数,不要按你请求的值算,否则会漏数据。

时间格式

两种形态并存,取决于接口 —— 每个接口页都注明了用哪种:

形态	例子	常见于
毫秒时间戳	`1788451200000`	统计、日志类接口
ISO 8601 字符串	`"2026-08-30T19:31:49.890Z"`	账号、站点等实体的时间字段

数据范围

所有接口都自动限定在你自己的账号范围内。不需要、也不能通过传 user_id 去访问别人的数据 —— 这类参数会被忽略或拒绝。

幂等与重试

所有 GET 都是只读的,可以安全重试。
POST /api/sites/{id}/update 是增量更新:同样的请求重复发多次,结果与发一次相同。
POST /api/sites(建站)不幂等 —— 重试前请先用站点列表确认上一次是否已经成功。