KiteKite

API 概述

Kite HTTP API 的基础约定：路径、鉴权、响应结构、错误码。

Kite 提供一套 RESTful HTTP API，所有业务端点均位于 /api/v1/ 前缀下，文件访问短链则直接挂在根路径下。

文档格式约定

本章所有接口文档统一采用以下结构：

  1. 接口定义（方法 + 路径 + 认证要求）
  2. 请求参数（Query / Path / Body / FormData）
  3. 请求示例（curl 或原始 HTTP）
  4. 响应示例（成功）
  5. 错误码（按场景列出）

请求生命周期

MERMAID
Mermaid 图表加载中...

Base URL

环境URL
本地开发http://localhost:8080/api/v1
生产部署https://kite.your-domain.com/api/v1

鉴权方式

Kite 支持两种认证方式：

Bearer Token（推荐）

在请求头中携带 Authorization: Bearer <token>。Token 可以是：

  • Access Token：POST /auth/login 返回的短期令牌（默认 2 小时）
  • API Token：POST /tokens 创建的长期令牌，适用于第三方客户端
HTTP
GET /api/v1/profile HTTP/1.1
Host: kite.your-domain.com
Authorization: Bearer eyJhbGciOi...
MERMAID
Mermaid 图表加载中...

POST /auth/login 成功后，Kite 会同时把 Access Token 写入 HttpOnly Cookie（access_token），用于 Web 后台的浏览器会话。API 调用请优先使用 Bearer。

统一响应结构

所有 /api/v1/** 端点返回如下结构：

JSON
{
  "code": 0,
  "message": "success",
  "data": {}
}
字段类型说明
codeint业务状态码，0 表示成功
messagestring人类可读的消息
dataany响应负载，可能为对象/数组/null
说明

例外：POST /api/v1/upload 与 POST /api/v1/public/upload 为兼容兰空 v2 协议，返回 {status, message, data} 结构。具体参见 文件上传。

分页响应

需要分页的列表接口返回 PagedData：

JSON
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [ /* ... */ ],
    "total": 128,
    "page": 1,
    "size": 20
  }
}
请求参数默认上限说明
page1—页码，从 1 开始
size20100每页数量
order_bycreated_at—排序字段（列表接口）
orderDESC—排序方向：ASC / DESC

HTTP 状态码与业务码

业务码采用 HTTP 状态码 × 100 + 细分编号 的形式。常见映射：

HTTPCode含义
2000成功
2010已创建（POST 资源）
40040000请求参数错误
40140100未认证
40340300禁止访问
40440400资源不存在
40940900冲突（如用户名已存在）
41341300文件超出大小限制
41541500文件类型被禁止
50050000服务器内部错误
50750700存储空间不足

速率限制

以下端点有默认速率限制（基于客户端 IP）：

端点限制
POST /auth/login每分钟 20 次
POST /auth/register每分钟 20 次
POST /auth/refresh每分钟 20 次
POST /public/upload每分钟 10 次

超出限制时返回 429 Too Many Requests。

API 分组

分组路径前缀认证说明
认证/auth/*部分需认证登录、注册、Token 刷新
文件上传/upload、/public/uploadBearer / 可选兰空 v2 兼容协议
文件管理/files/*Bearer列表、详情、删除、批量
相册/albums/*Bearer相册 CRUD
API Token/tokens/*Bearer令牌管理
管理员/admin/*Bearer + Admin用户/存储/设置
公开/public/*无统计、广场、游客上传

文件访问短链

文件上传后，访问链接不在 /api/v1/ 下，而是直接挂根：

前缀用途
/i/:hash图片
/v/:hash视频
/a/:hash音频
/f/:hash下载（带 Content-Disposition: attachment）
/t/:hash缩略图

:hash 为文件 MD5 的前 8 位。详见 文件上传。

下一步