news 2026/7/21 17:45:39

Pygmy API开发指南：如何使用REST接口创建和管理短链接

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Pygmy API开发指南：如何使用REST接口创建和管理短链接

Pygmy API开发指南：如何使用REST接口创建和管理短链接

【免费下载链接】pygmyAn open-source, feature rich & extensible url-shortener + analytics written in Python :cookie:项目地址: https://gitcode.com/gh_mirrors/py/pygmy

Pygmy是一个功能丰富的开源URL缩短器和分析工具，使用Python构建。本指南将详细介绍如何利用Pygmy的REST API接口创建、管理和跟踪短链接，帮助开发者快速集成URL缩短功能到自己的应用中。

快速开始：API接口概览

Pygmy提供了完整的RESTful API接口，主要包括以下核心功能：

  • 创建短链接：通过POST请求将长URL转换为简洁的短链接
  • 解析短链接：通过GET请求获取短链接对应的原始长URL
  • 链接管理：支持自定义短码、设置过期时间和添加描述
  • 访问统计：提供详细的点击数据和访问分析

所有API端点都以/api/为前缀，完整的接口定义可在pygmy/rest/urls.py中查看。

API认证与授权

Pygmy API使用JWT（JSON 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：必需，要缩短的原始长URL
  • short_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?url=<short_code>
示例：
GET /api/unshorten?url=abc123
成功响应：
{ "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", json=AUTH_CREDENTIALS) tokens = response.json() headers = {"Authorization": f"Bearer {tokens['access_token']}"} # 创建短链接 shorten_response = requests.post( f"{API_BASE_URL}/shorten", headers=headers, 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']}", headers=headers ) 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），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/7/20 16:14:18

告别挂机烦恼：三分钟掌握Twitch自动掉宝神器

告别挂机烦恼&#xff1a;三分钟掌握Twitch自动掉宝神器 【免费下载链接】TwitchDropsMiner An app that allows you to AFK mine timed Twitch drops, with automatic drop claiming and channel switching. 项目地址: https://gitcode.com/GitHub_Trending/tw/TwitchDropsM…

作者头像 李华
网站建设 2026/7/20 16:11:39

加密不等于安全

很多开发者认为&#xff0c;只要对消息内容做了端到端加密&#xff0c;通信就是安全的。但现实远比这复杂。 让我们看一个场景&#xff1a;假设你在使用一个加密聊天软件&#xff0c;每条消息发送时&#xff0c;网络上会出现一个约 1500 字节的数据包&#xff0c;每隔 5 秒准时…

作者头像 李华
网站建设 2026/7/20 16:10:34

企业级可视化编辑器完整部署策略与3大核心价值实现

企业级可视化编辑器完整部署策略与3大核心价值实现 【免费下载链接】onlook The Cursor for Designers • An Open-Source AI-First Design tool • Visually build, style, and edit your React App with AI 项目地址: https://gitcode.com/GitHub_Trending/on/onlook …

作者头像 李华
网站建设 2026/7/20 16:10:33

C++11可变参数模板与emplace实战：提升代码性能与表现力

1. 项目概述&#xff1a;C11新特性的深度实践与理解作为一名在C领域摸爬滚打了十多年的老码农&#xff0c;我亲眼见证了C11标准发布时给整个社区带来的那种“焕然一新”的震撼。它不仅仅是语法糖的堆砌&#xff0c;更是一次编程范式和思维方式的升级。今天&#xff0c;我们不谈…

作者头像 李华
网站建设 2026/7/20 16:10:19

C 语言分支与循环语句深度详解

一、前置核心概念语句&#xff1a;分号 ; 结尾的代码单元&#xff1b; 代码块&#xff08;复合语句&#xff09;&#xff1a;{ } 包裹&#xff0c;逻辑上视为一条语句&#xff0c;分支 / 循环后多条代码必须加大括号&#xff1b; 逻辑真假&#xff1a;C 语言没有布尔类型&#…

作者头像 李华
网站建设 2026/7/20 16:05:26

Cap：3个神奇功能让屏幕录制变得如此简单有趣

Cap&#xff1a;3个神奇功能让屏幕录制变得如此简单有趣 【免费下载链接】Cap Open source Loom alternative. Beautiful, shareable screen recordings. 项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap 想象一下&#xff0c;你正在为团队演示一个新功能&…

作者头像 李华