Skip to content

api.md

Latest commit

 

History

History
146 lines (96 loc) · 2.81 KB

api.md

File metadata and controls

146 lines (96 loc) · 2.81 KB
Raw

API 文档

本文档描述短链解析系统对外提供的 HTTP API。

通用约定

  • 所有请求/响应体使用 UTF-8 编码
  • 日期时间格式遵循 ISO 8601（如 2026-05-30T00:00:00Z）
  • 认证失败统一返回 401，错误信息为中文

1. 健康检查

GET /health

检查服务可用性。

响应 (200)

{
  "status": "ok"
}

2. 生成短链

POST /api/v1/shorten

将长 URL 转换为短链。

请求头

Authorization: Bearer {token}
Content-Type: application/json

请求体

{
  "url": "https://example.com/very/long/path?param=value",
  "expires_at": "2026-05-30T00:00:00Z"
}
  • url（必填）：原始长 URL，最大长度 2048
  • expires_at（可选）：过期时间，不填则永久有效

成功响应 (201)

{
  "code": "6yP3Hx",
  "short_url": "http://s.example.com/6yP3Hx",
  "original_url": "https://example.com/very/long/path?param=value",
  "expires_at": "2026-05-30T00:00:00Z"
}

错误响应

状态码 场景 响应体
400 URL 格式非法 {"error":"URL格式非法","code":"INVALID_URL"}
401 Token 无效或缺失 {"error":"认证失败","code":"UNAUTHORIZED"}
500 系统繁忙（重试耗尽） {"error":"系统繁忙，请稍后重试","code":"INTERNAL_ERROR"}

去重策略

  • 同一 original_url 重复调用时，返回已存在的未删除短链
  • 若该短链已被逻辑删除，则重新生成新的短链码

3. 删除短链

DELETE /api/v1/shorten/{code}

逻辑删除指定短链。

请求头

Authorization: Bearer {token}

成功响应 (200)

{
  "message": "删除成功"
}

错误响应

状态码 场景 响应体
401 Token 无效或缺失 {"error":"认证失败","code":"UNAUTHORIZED"}
404 短链不存在或已删除 {"error":"短链不存在","code":"NOT_FOUND"}

4. 解析短链

GET /{code}

访问短链，系统根据短链状态返回对应响应。

成功响应 (302)

Location: https://example.com/very/long/path?param=value

错误响应

状态码 场景 响应体
404 短链不存在或已删除 中文 HTML 页面，显示"链接不存在"
410 短链已过期 中文 HTML 页面，显示"链接已过期"

状态判断优先级

  1. deleted_at IS NOT NULL → 404
  2. expires_at IS NOT NULL AND expires_at < NOW() → 410
  3. 以上均不满足 → 302 跳转

认证说明

V1 采用静态 Token 列表（MVP 临时方案），请求时需在 Authorization 头中携带：

Authorization: Bearer your-secret-token

Token 在 configs/config.yaml 的 auth.tokens 中配置。V2 将迁移至 JWT 或数据库 Token 管理。