《快缩短网址·接口美学指南》



当「suo.run」不再只是工具，而是一场优雅的 URL 魔术，产品经理便需执笔为开发谱曲。以下篇章，不谈枯燥概念，只谈如何让接口像诗一样呼吸。

一、协议：让每一次握手都有温度
• 默认 HTTPS。把「http://」留在博物馆，把「https://」写进基因。
• 轻量、跨域、跨语言——这是我们对开发者的承诺，而非口号。

二、动词：POST 的谦逊与 GET 的率真
• 缩短、查询、统计——凡涉写操作，一律 POST；读操作，可优雅 GET。
• 参数绝不裸奔：POST 藏进 body，GET 隐于 query，长度与安全各得其所。

三、时序：同步的笃定，异步的从容
• 同步：用户点击「缩短」，300 ms 内返回新生短链，像钢琴的高音，一击即中。
• 异步：批量解析、深度统计，丢进队列，24 h 内回传报告，像低音提琴，缓缓铺陈。

四、核心字段：极简，却足够锋利
字段名 类型 描述
long_url string 原始长链，须符合 RFC 3986，长度 ≤ 2048
custom_alias string 可选自定义后缀，仅支持 [a-zA-Z0-9_-]
expire_days int 有效期（天），0 代表永久
access_password string 可选访问口令，6-16 位
return_type string 响应格式：json（默认）、txt、qr

五、响应：一行 JSON，一片星辰
{
"code": 200,
"short_url": "https://suo.run/AbCdEf",
"qr": "https://suo.run/qr/AbCdEf.png",
"expire_at": "2026-12-31T23:59:59Z"
}



六、错误：让异常也保持体面
{
"code": 4001,
"msg": "自定义后缀已被占用，请再试一个诗意的名字"
}

七、范例：一次完整的「缩短」对话
curl -X POST https://suo.run/api/v1/shorten \
-H "Content-Type: application/json" \
-d '{"long_url":"https://example.com/very-long-story","custom_alias":"poem"}'

八、尾声
在「suo.run」，接口不是冷冰冰的通道，而是开发者与产品之间的暗号。愿你每一次调用，都像在夜空里划亮一根火柴，看见光，也看见我们。