标准 API 接口文档

占位符约定

一、路由与认证

标准 API 的业务路由为：

除 /api/ping 外，标准链路只从以下来源提取凭证：

1. X-Token 请求头，优先级最高，GET/POST 均可使用。
2. JSON 请求体中的字符串字段 key，仅在没有 X-Token 时使用。
3. X-Headless-Token 在标准链路中不会被接受。

因此 POST 示例可以继续把 Key 放在请求体中，但统一封装时也可以全部使用 X-Token。若两处同时提供，服务器只验证 X-Token，不会在其无效时回退到 body.key。

Key 类型与限制

Key 明文只在 CLI 生成时显示。服务端仅保存 SHA-256 哈希和前缀；比较使用 hash_equals。一次性池不会自动补充，需要通过 CLI 维护。

二、健康检查

GET /api/ping

{ "ok": true }

该端点直接由 api/ping.php 输出，不加载业务 bootstrap，因此无需 Key，不检查数据文件、domain、panel_enabled，也不设置业务 CORS 头。它只证明 PHP-FPM 与该路由可用，不证明短链存储、认证或 OpenResty 热存储正常。

三、创建短链

POST /api/create
Content-Type: application/json
X-Token: {su_你的Key}

{
  "url": "{目标长链接}",
  "ttl": 0,
  "code": "demo"
}

四、删除短链

POST /api/delete
Content-Type: application/json
X-Token: {su_你的Key}

{ "code": "{短链后缀}" }

code 必须存在且为字符串，trim 后不能为空，随后转为小写。该接口不再次做 1-4 位正则校验，而是按值查询冷存储。一次性 Key 已在认证阶段消费，随后会返回 403。

{ "ok": true, "synced": true }

删除先提交冷存储，再调用内部接口删除热存储。synced=false 表示冷存储已删除但热存储同步失败，不回滚冷存储。

五、查询列表

GET /api/list
X-Token: {su_你的Key}

{
  "permanent": [
    { "id": "a1b2", "url": "https://example.com/", "lurl": "https://{你的域名}/a1b2", "exp": "permanent" }
  ],
  "temporary": [
    { "id": "demo", "url": "https://example.com/page", "lurl": "https://{你的域名}/demo", "exp": "{ISO 8601 过期时间}" }
  ]
}

列表直接读取冷存储；永久条目的 exp 固定为 "permanent"，临时列表过滤已过期条目，但不会仅因查询而把过期条目写回删除。一次性 Key 返回 403。存储损坏返回结构化 500。

六、查询统计

GET /api/stat
X-Token: {su_你的Key}

{
  "perm_count": 12,
  "temp_count": 3,
  "perm_limit": 10000,
  "temp_limit": 500,
  "hot_available": true,
  "hot_perm_count": 12,
  "hot_temp_count": 3
}

热存储不可用时仍返回 200，hot_available 为 false，并省略两个 hot_*_count 字段。一次性 Key 返回 403。

七、通用错误与 430

标准链路错误体为：

{ "error": "中文描述" }

430 检查发生在认证之前，客户端收到的消息固定为：

{ "error": "数据文件不可访问，请检查文件权限" }

具体失败文件名只写服务器日志，不再暴露给客户端。检查范围默认是 perm.json、temp.json、keys.json：文件存在时要求可读且可写；文件不存在时要求父目录存在且可写。不要依赖固定的 666/777 数字权限，实际要求取决于 PHP-FPM 用户、属主、组和挂载方式。

panel_enabled=false 会在数据检查和认证之前让标准业务 API 返回 403：

{ "error": "前端面板未启用" }

/api/ping 不受该开关影响。

八、CORS

标准业务 API 的 bootstrap 设置：

Access-Control-Allow-Origin: {panel_origin 或 domain}
Access-Control-Allow-Headers: Content-Type, X-Token
Access-Control-Allow-Methods: GET, POST, OPTIONS

允许源优先取 config.php 的 panel_origin；为空时才回退到短链 domain。它应配置为实际前端面板 Origin，而不是默认理解为短链域名。业务路由的 OPTIONS 由 PHP 返回 204 No Content，但前提是 panel_enabled=true；开关关闭时会先返回 403。无头 API 不设置 CORS。/api/ping 也不加载这组 CORS 头。