Kutt.it 短链接服务API全面解析

概述

Kutt.it是一个开源的短链接服务，提供了完善的API接口供开发者集成使用。本文将对Kutt.it的API进行详细解析，帮助开发者快速理解和使用这套接口系统。

API基础信息

Kutt.it API基于OpenAPI 3.0.0规范构建，当前版本与项目主版本保持一致。API基础端点位于https://kutt.it/api/v2，所有请求都需要在Header中携带X-API-KEY进行身份验证。

主要功能模块

1. 健康检查接口

GET /health

这是一个简单的健康检查接口，返回"OK"表示服务正常运行。适合用于监控系统对API可用性的检测。

2. 短链接管理

获取短链接列表

GET /links

参数说明：

• limit: 返回结果数量限制，默认10
• skip: 跳过前N条记录，用于分页
• all: 管理员专用，获取所有用户的链接

创建短链接

POST /links

请求体参数：

• target: 必填，原始URL
• description: 可选，链接描述
• expire_in: 可选，过期时间(如"2 days")
• password: 可选，访问密码
• customurl: 可选，自定义短链
• reuse: 可选，是否重用已有短链
• domain: 可选，指定域名

更新短链接

PATCH /links/{id}

路径参数：

• id: 链接UUID

请求体参数：

• target: 必填，新目标URL
• address: 必填，短链地址
• description: 可选，新描述
• expire_in: 可选，新过期时间

删除短链接

DELETE /links/{id}

路径参数：

• id: 链接UUID

获取链接统计

GET /links/{id}/stats

返回详细的访问统计数据，包括：

• 按时间段统计(最近天/周/月/年)
• 浏览器分布
• 操作系统分布
• 国家地区分布
• 来源统计

3. 域名管理

添加自定义域名

POST /domains

请求体参数：

• address: 必填，域名地址
• homepage: 可选，主页URL

删除域名

DELETE /domains/{id}

路径参数：

• id: 域名UUID

4. 用户信息

获取用户信息

GET /users

返回当前用户的基本信息，包括：

• API密钥
• 邮箱
• 关联的域名列表

数据结构说明

链接(Link)结构

{
  "address": "短链地址",
  "banned": "是否被封禁",
  "created_at": "创建时间",
  "id": "UUID",
  "link": "完整短链URL",
  "password": "是否有密码",
  "target": "目标URL",
  "description": "描述",
  "updated_at": "更新时间",
  "visit_count": "访问次数"
}

域名(Domain)结构

{
  "address": "域名",
  "banned": "是否被封禁",
  "created_at": "创建时间",
  "id": "UUID",
  "homepage": "主页URL",
  "updated_at": "更新时间"
}

统计(Stats)结构

提供多维度的访问数据分析，包括时间序列数据和分类统计数据。

安全认证

所有API请求都需要在Header中添加：

X-API-KEY: 您的API密钥

最佳实践建议

1. 错误处理：所有API调用都应做好错误处理，检查HTTP状态码
2. 频率限制：避免高频调用，建议实现适当的缓存机制
3. 数据验证：在客户端对输入数据进行验证，特别是URL格式
4. 敏感信息：不要在短链接中包含敏感信息，即使有密码保护
5. 监控：对关键业务短链接实现访问监控

总结

Kutt.it提供了一套完整、规范的API接口，涵盖了短链接服务的核心功能。通过合理使用这些接口，开发者可以轻松地将短链接功能集成到自己的应用中，实现URL缩短、统计跟踪等功能。API设计遵循RESTful原则，数据结构清晰，认证机制简单有效，是开发者构建短链接相关功能的理想选择。