Pygmy API开发指南如何使用REST接口创建和管理短链接【免费下载链接】pygmyAn open-source, feature rich extensible url-shortener analytics written in Python :cookie:项目地址: https://gitcode.com/gh_mirrors/py/pygmyPygmy是一个功能丰富的开源URL缩短器和分析工具使用Python构建。本指南将详细介绍如何利用Pygmy的REST API接口创建、管理和跟踪短链接帮助开发者快速集成URL缩短功能到自己的应用中。快速开始API接口概览Pygmy提供了完整的RESTful API接口主要包括以下核心功能创建短链接通过POST请求将长URL转换为简洁的短链接解析短链接通过GET请求获取短链接对应的原始长URL链接管理支持自定义短码、设置过期时间和添加描述访问统计提供详细的点击数据和访问分析所有API端点都以/api/为前缀完整的接口定义可在pygmy/rest/urls.py中查看。API认证与授权Pygmy API使用JWTJSON Web Token进行身份验证确保接口调用的安全性。获取访问令牌POST /api/token通过提供用户名和密码获取访问令牌和刷新令牌{ username: your_username, password: your_password }成功响应将包含access_token用于API授权的主要令牌refresh_token用于获取新的访问令牌使用令牌进行授权在所有API请求的头部中包含以下授权信息Authorization: Bearer access_token令牌管理的核心实现位于pygmy/app/auth.py其中包含了令牌创建、刷新和黑名单管理的完整逻辑。创建短链接核心功能详解创建短链接是Pygmy API最核心的功能通过简单的POST请求即可实现。基础创建接口POST /api/shorten请求参数long_url必需要缩短的原始长URLshort_code可选自定义短链接码如不提供则自动生成expire_after可选链接过期时间单位秒description可选链接描述信息示例请求{ long_url: https://example.com/very/long/url/path, description: 示例长链接 }成功响应{ short_code: abc123, short_url: http://pygmy.example/abc123, long_url: https://example.com/very/long/url/path, created_at: 2026-07-19T10:30:45Z, expires_at: null, description: 示例长链接 }短链接创建的核心逻辑实现于pygmy/app/link.py中的shorten函数该函数处理URL验证、短码生成和数据库存储等关键步骤。自定义短码如果需要指定自定义短码只需在请求中添加short_code参数{ long_url: https://example.com/special/page, short_code: special, description: 自定义短码示例 }如果指定的短码已被占用API将返回409 Conflict错误提示短码不可用。解析与管理短链接解析短链接要获取短链接对应的原始长URL使用以下接口GET /api/unshorten?urlshort_code示例GET /api/unshorten?urlabc123成功响应{ long_url: https://example.com/very/long/url/path, short_code: abc123, created_at: 2026-07-19T10:30:45Z }解析功能由pygmy/app/link.py中的unshorten函数实现该函数处理短码验证、访问统计记录和URL重定向等操作。获取链接统计信息Pygmy提供了详细的链接访问统计功能通过以下接口获取GET /api/stats/short_code示例响应{ short_code: abc123, long_url: https://example.com/very/long/url/path, total_clicks: 42, daily_clicks: [ {date: 2026-07-19, count: 15}, {date: 2026-07-18, count: 27} ], referrers: [ {source: twitter.com, count: 18}, {source: google.com, count: 12}, {source: direct, count: 12} ], countries: [ {country: United States, count: 24}, {country: United Kingdom, count: 8}, {country: Canada, count: 5} ] }统计功能的实现位于pygmy/app/link.py中的link_stats函数结合了地理信息数据库pygmy/app/GeoLite2-Country.mmdb提供位置分析。实际应用示例Python请求示例以下是使用Python的requests库调用Pygmy API的完整示例import requests API_BASE_URL http://your-pygmy-instance.com/api AUTH_CREDENTIALS (username, password) # 获取访问令牌 response requests.post(f{API_BASE_URL}/token, jsonAUTH_CREDENTIALS) tokens response.json() headers {Authorization: fBearer {tokens[access_token]}} # 创建短链接 shorten_response requests.post( f{API_BASE_URL}/shorten, headersheaders, json{ long_url: https://example.com/very/long/url, description: API示例链接 } ) short_url_data shorten_response.json() print(f创建的短链接: {short_url_data[short_url]}) # 获取链接统计 stats_response requests.get( f{API_BASE_URL}/stats/{short_url_data[short_code]}, headersheaders ) print(链接统计:, stats_response.json())前端集成示例Pygmy还提供了前端JavaScript客户端位于pygmyui/restclient/pygmy.py可轻松集成到Web应用中// 初始化Pygmy客户端 const pygmyClient new PygmyClient(http://your-pygmy-instance.com); // 用户登录 pygmyClient.login(username, password) .then(tokens { console.log(登录成功访问令牌:, tokens.access_token); // 创建短链接 return pygmyClient.shorten(https://example.com/frontend-integration); }) .then(shortUrlData { console.log(创建的短链接:, shortUrlData.short_url); }) .catch(error { console.error(操作失败:, error); });错误处理与状态码Pygmy API使用标准HTTP状态码表示请求结果200 OK请求成功201 Created资源创建成功如短链接创建400 Bad Request请求参数错误401 Unauthorized未授权或令牌过期403 Forbidden权限不足404 Not Found短链接不存在409 Conflict自定义短码已存在500 Internal Server Error服务器内部错误详细的错误处理逻辑可在pygmy/exception/目录中找到包含了各种特定错误类型的定义和处理方法。高级功能与扩展批量操作Pygmy支持批量创建短链接通过发送包含多个URL的数组实现POST /api/shorten/batch链接权限控制可以为短链接设置访问密码或限制特定IP访问{ long_url: https://example.com/private, secret_key: securepassword, allowed_ips: [192.168.1.0/24, 10.0.0.1] }这些高级功能的实现位于pygmy/validator/link.py中提供了全面的链接验证和权限控制机制。总结与资源Pygmy提供了一套功能完善、易于使用的REST API接口使开发者能够轻松集成URL缩短和分析功能到自己的应用中。无论是简单的短链接创建还是复杂的访问统计分析Pygmy都能满足各种场景需求。要开始使用Pygmy API首先克隆项目仓库git clone https://gitcode.com/gh_mirrors/py/pygmy项目的完整文档和更多示例可在以下资源中找到API接口定义pygmy/rest/urls.py核心功能实现pygmy/app/link.py认证机制pygmy/app/auth.py测试用例tests/test_integration.py通过本指南您应该已经掌握了Pygmy API的基本使用方法。如需了解更多高级功能和最佳实践请参考项目源代码和测试用例。【免费下载链接】pygmyAn open-source, feature rich extensible url-shortener analytics written in Python :cookie:项目地址: https://gitcode.com/gh_mirrors/py/pygmy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考