介绍
# Jo4 - URL Shortener & Analytics API
Jo4 是一款现代化的短链接服务，支持二维码生成和详细的链接分析。
## Authentication（身份验证）
所有受保护的端点都需要 API 密钥。将您的 API 密钥设置为环境变量：
```bash export JO4_API_KEY="your-api-key" ```
从以下地址获取您的 API 密钥： https://jo4.io/api-keys
## API Base URL（API 基础 URL）
``` https://jo4-api.jo4.io/api/v1 ```
## Endpoints（端点）
### Create Short URL (Authenticated)（创建短链接 - 需要身份验证）
```bash curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \ -H "X-API-Key: $JO4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "longUrl": "https://example.com/very-long-url", "title": "My Link" }' ```
**Request Body（请求体）：** - `longUrl`（必填）- 目标 URL（最多 2048 个字符） - `title`（可选）- 链接标题（最多 200 个字符） - `description`（可选）- 链接描述（最多 500 个字符） - `shortUrl`（可选）- 自定义别名（最多 16 个字符，字母数字/连字符/下划线） - `expirationTime`（可选）- 链接过期时间的 Unix 时间戳 - `passwordProtected`（可选）- 启用密码保护的布尔值 - `password`（可选）- 如果受保护，则为密码（4-128 个字符）
**UTM Parameters（UTM 参数）：** - `utmSource`、`utmMedium`、`utmCampaign`、`utmTerm`、`utmContent`
**Response（响应）：** ```json { "response": { "id": 123, "slug": "abc123", "shortUrl": "abc123", "fullShortUrl": "https://jo4.io/a/abc123", "longUrl": "https://example.com/very-long-url", "title": "My Link", "qrCodeUrl": "https://jo4.io/qr/abc123" } } ```
### Create Anonymous Short URL (No Auth Required)（创建匿名短链接 - 无需身份验证）
```bash curl -X POST "https://jo4-api.jo4.io/api/v1/public/url" \ -H "Content-Type: application/json" \ -d '{"longUrl": "https://example.com"}' ```
功能受限，无分析数据访问权限。
### Get URL Details（获取 URL 详情）
```bash curl -X GET "https://jo4-api.jo4.io/api/v1/protected/url/{slug}" \ -H "X-API-Key: $JO4_API_KEY" ```
### Get URL Analytics（获取 URL 分析数据）
```bash curl -X GET "https://jo4-api.jo4.io/api/v1/protected/url/{slug}/stats" \ -H "X-API-Key: $JO4_API_KEY" ```
**Response includes（响应包括）：** - 总点击量 - 按日期统计的点击量 - 地理分布 - 设备/浏览器细分 - 来源来源
### List My URLs（列出我的 URL）
```bash curl -X GET "https://jo4-api.jo4.io/api/v1/protected/url/myurls?page=0&size=20" \ -H "X-API-Key: $JO4_API_KEY" ```
### Update URL（更新 URL）
```bash curl -X PUT "https://jo4-api.jo4.io/api/v1/protected/url/{id}" \ -H "X-API-Key: $JO4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Updated Title", "longUrl": "https://new-destination.com" }' ```
### Delete URL（删除 URL）
```bash curl -X DELETE "https://jo4-api.jo4.io/api/v1/protected/url/{id}" \ -H "X-API-Key: $JO4_API_KEY" ```
## QR Codes（二维码）
每个短链接都会自动在以下位置生成二维码： ``` https://jo4.io/qr/{shortUrl} ```
## Rate Limits（速率限制）
速率限制因计划而异： - Free（免费版）：60 次/分钟 - Pro（专业版）：最多 10,000 次/分钟 - Anonymous（匿名，公共端点）：10 次/分钟
## API Documentation（API 文档）
完整的 OpenAPI/Swagger 文档： https://jo4-api.jo4.io/swagger-ui/index.html
## Common Use Cases（常见用例）
### 1. Shorten a URL for sharing（缩短 URL 以便分享） ```bash curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \ -H "X-API-Key: $JO4_API_KEY" \ -H "Content-Type: application/json" \ -d '{"longUrl": "https://example.com/article", "title": "Article"}' ```
### 2. Create campaign tracking link（创建活动跟踪链接） ```bash curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \ -H "X-API-Key: $JO4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "longUrl": "https://mysite.com/landing", "title": "Q1 Campaign", "utmSource": "twitter", "utmMedium": "social", "utmCampaign": "q1-2026" }' ```
### 3. Create expiring link（创建过期链接） ```bash curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \ -H "X-API-Key: $JO4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "longUrl": "https://mysite.com/promo", "title": "Limited Offer", "expirationTime": 1738454400 }' ```
## Error Codes（错误代码）
| Code | Meaning | |------|---------| | 400 | Bad request - invalid parameters（错误请求 - 无效参数） | | 401 | Unauthorized - missing or invalid API key（未授权 - 缺少或无效的 API 密钥） | | 403 | Forbidden - insufficient permissions（禁止访问 - 权限不足） | | 404 | Not found - URL doesn't exist（未找到 - URL 不存在） | | 429 | Rate limit exceeded（超过速率限制） |