GithubBackup/SaveAny-Bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add API documentation in English and Chinese

Browse Source 
Co-authored-by: krau <71133316+krau@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-01-19 04:44:20 +00:00
parent ac10c32215
commit 2f6b2470a4
3 changed files with 550 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
api/README.md Normal file
View File

@@ -0,0 +1,26 @@
# API Module
This module provides a RESTful HTTP API for programmatic file downloads from Telegram.
## Features
- **RESTful API endpoints** for creating, querying, and canceling download tasks
- **Bearer token authentication** for API access control
- **IP whitelist** support for additional security
- **Webhook callbacks** for task completion notifications
- **Task status tracking** (queued, running, completed, failed, canceled)
- **Graceful shutdown** with proper cleanup
## Usage
See the full documentation at:
- English: `/docs/content/en/usage/api.md`
- Chinese: `/docs/content/zh/usage/api.md`
## Architecture
- `server.go` - HTTP server initialization and route registration
- `handlers.go` - API endpoint handlers and business logic
- `middleware.go` - Authentication and logging middleware
The API integrates with the existing task queue system and uses the bot's Telegram client to fetch messages.

262
docs/content/en/usage/api.md Normal file
View File

@@ -0,0 +1,262 @@
---
title: "HTTP API"
weight: 4
---
# HTTP API
SaveAny-Bot provides a RESTful HTTP API for programmatic file downloads from Telegram.
## Configuration
Enable the API in your `config.toml`:
```toml
[api]
# Enable HTTP API service
enable = true
# API server listen port
port = 8080
# API access token (leave empty to disable authentication)
token = "your-secret-token-here"
# Task completion callback webhook URL (leave empty to disable)
webhook_url = "https://your-server.com/webhook"
# Trusted IP addresses (leave empty to allow all), supports single IP or CIDR notation
trusted_ips = ["127.0.0.1", "192.168.1.0/24"]
```
## Authentication
If `token` is configured, all API requests (except `/health`) must include an `Authorization` header:
```
Authorization: Bearer your-secret-token-here
```
If `trusted_ips` is configured, requests will only be accepted from specified IP addresses.
## Endpoints
### Health Check
Check if the API server is running.
**Request:**
```
GET /health
```
**Response:**
```json
{
"status": "ok"
}
```
### Create Download Task
Create a new file download task from a Telegram message link.
**Request:**
```
POST /api/v1/tasks
Content-Type: application/json
Authorization: Bearer your-secret-token-here
{
"telegram_url": "https://t.me/channel/123",
"user_id": 123456789,
"storage_name": "local1",
"dir_path": "/downloads"
}
```
**Request Parameters:**
- `telegram_url` (required): Telegram message link (e.g., `https://t.me/channel/123`)
- `user_id` (required): Telegram user ID (must be configured in `config.toml`)
- `storage_name` (optional): Storage name to use. If not specified, uses the first available storage for the user
- `dir_path` (optional): Directory path in storage. Default is `/`
**Response (201 Created):**
```json
{
"task_id": "c9h8t1234abcd",
"message": "task created successfully"
}
```
**Error Response (4xx/5xx):**
```json
{
"error": "error description"
}
```
### Get Task Status
Get the status of a specific task.
**Request:**
```
GET /api/v1/tasks/{task_id}
Authorization: Bearer your-secret-token-here
```
**Response (200 OK):**
```json
{
"task_id": "c9h8t1234abcd",
"status": "completed",
"title": "[tgfiles](file.pdf->local1:/downloads/file.pdf)",
"created_at": "2024-01-19T04:30:00Z",
"error": ""
}
```
**Status Values:**
- `queued`: Task is waiting in queue
- `running`: Task is currently downloading
- `completed`: Task completed successfully
- `failed`: Task failed with error (see `error` field)
- `canceled`: Task was canceled
### List All Tasks
List all queued and running tasks.
**Request:**
```
GET /api/v1/tasks
Authorization: Bearer your-secret-token-here
```
**Response (200 OK):**
```json
{
"queued": [
{
"id": "c9h8t1234abcd",
"title": "[tgfiles](file1.pdf->local1:/downloads/file1.pdf)"
}
],
"running": [
{
"id": "d2k9u5678efgh",
"title": "[tgfiles](file2.pdf->local1:/downloads/file2.pdf)"
}
]
}
```
### Cancel Task
Cancel a running or queued task.
**Request:**
```
DELETE /api/v1/tasks/{task_id}
Authorization: Bearer your-secret-token-here
```
**Response (200 OK):**
```json
{
"message": "task canceled"
}
```
## Webhook Callback
If `webhook_url` is configured, the API will send a POST request to the webhook URL when a task completes or fails.
**Webhook Request:**
```
POST {webhook_url}
Content-Type: application/json
Authorization: Bearer your-secret-token-here
{
"task_id": "c9h8t1234abcd",
"status": "completed",
"title": "[tgfiles](file.pdf->local1:/downloads/file.pdf)",
"created_at": "2024-01-19T04:30:00Z",
"error": ""
}
```
## Example Usage
### Using cURL
**Create a download task:**
```bash
curl -X POST http://localhost:8080/api/v1/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret-token-here" \
-d '{
"telegram_url": "https://t.me/channel/123",
"user_id": 123456789,
"storage_name": "local1",
"dir_path": "/downloads"
}'
```
**Get task status:**
```bash
curl http://localhost:8080/api/v1/tasks/c9h8t1234abcd \
-H "Authorization: Bearer your-secret-token-here"
```
**List all tasks:**
```bash
curl http://localhost:8080/api/v1/tasks \
-H "Authorization: Bearer your-secret-token-here"
```
**Cancel a task:**
```bash
curl -X DELETE http://localhost:8080/api/v1/tasks/c9h8t1234abcd \
-H "Authorization: Bearer your-secret-token-here"
```
### Using Python
```python
import requests
API_URL = "http://localhost:8080"
TOKEN = "your-secret-token-here"
HEADERS = {
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json"
}
# Create a download task
response = requests.post(
f"{API_URL}/api/v1/tasks",
headers=HEADERS,
json={
"telegram_url": "https://t.me/channel/123",
"user_id": 123456789,
"storage_name": "local1",
"dir_path": "/downloads"
}
)
task_id = response.json()["task_id"]
# Get task status
response = requests.get(
f"{API_URL}/api/v1/tasks/{task_id}",
headers=HEADERS
)
status = response.json()
print(f"Task status: {status['status']}")
```
## Security Recommendations
1. **Always use a strong token** for production environments
2. **Enable IP whitelist** (`trusted_ips`) to restrict access
3. **Use HTTPS** in production by placing the API behind a reverse proxy (e.g., Nginx, Caddy)
4. **Keep logs secure** as they may contain sensitive information
5. **Validate user permissions** - ensure `user_id` in requests corresponds to authorized users in your config

262
docs/content/zh/usage/api.md Normal file
View File

@@ -0,0 +1,262 @@
---
title: "HTTP API"
weight: 4
---
# HTTP API
SaveAny-Bot 提供 RESTful HTTP API，支持通过编程方式从 Telegram 下载文件。
## 配置
在 `config.toml` 中启用 API：
```toml
[api]
# 启用 HTTP API 服务
enable = true
# API 服务监听端口
port = 8080
# API 访问令牌 (留空则不验证)
token = "your-secret-token-here"
# 任务完成回调 Webhook URL (留空则不回调)
webhook_url = "https://your-server.com/webhook"
# 可信任的 IP 地址列表 (留空则不限制), 支持单个 IP 或 CIDR 格式
trusted_ips = ["127.0.0.1", "192.168.1.0/24"]
```
## 认证
如果配置了 `token`，所有 API 请求（除了 `/health`）都必须包含 `Authorization` 头：
```
Authorization: Bearer your-secret-token-here
```
如果配置了 `trusted_ips`，请求只会从指定的 IP 地址被接受。
## 端点
### 健康检查
检查 API 服务器是否正在运行。
**请求：**
```
GET /health
```
**响应：**
```json
{
"status": "ok"
}
```
### 创建下载任务
从 Telegram 消息链接创建新的文件下载任务。
**请求：**
```
POST /api/v1/tasks
Content-Type: application/json
Authorization: Bearer your-secret-token-here
{
"telegram_url": "https://t.me/channel/123",
"user_id": 123456789,
"storage_name": "local1",
"dir_path": "/downloads"
}
```
**请求参数：**
- `telegram_url` (必填): Telegram 消息链接 (例如: `https://t.me/channel/123`)
- `user_id` (必填): Telegram 用户 ID (必须在 `config.toml` 中配置)
- `storage_name` (可选): 要使用的存储名称。如果未指定，使用用户的第一个可用存储
- `dir_path` (可选): 存储中的目录路径。默认为 `/`
**响应 (201 Created)：**
```json
{
"task_id": "c9h8t1234abcd",
"message": "task created successfully"
}
```
**错误响应 (4xx/5xx)：**
```json
{
"error": "错误描述"
}
```
### 获取任务状态
获取特定任务的状态。
**请求：**
```
GET /api/v1/tasks/{task_id}
Authorization: Bearer your-secret-token-here
```
**响应 (200 OK)：**
```json
{
"task_id": "c9h8t1234abcd",
"status": "completed",
"title": "[tgfiles](file.pdf->local1:/downloads/file.pdf)",
"created_at": "2024-01-19T04:30:00Z",
"error": ""
}
```
**状态值：**
- `queued`: 任务正在队列中等待
- `running`: 任务正在下载
- `completed`: 任务成功完成
- `failed`: 任务失败（查看 `error` 字段）
- `canceled`: 任务已取消
### 列出所有任务
列出所有排队和正在运行的任务。
**请求：**
```
GET /api/v1/tasks
Authorization: Bearer your-secret-token-here
```
**响应 (200 OK)：**
```json
{
"queued": [
{
"id": "c9h8t1234abcd",
"title": "[tgfiles](file1.pdf->local1:/downloads/file1.pdf)"
}
],
"running": [
{
"id": "d2k9u5678efgh",
"title": "[tgfiles](file2.pdf->local1:/downloads/file2.pdf)"
}
]
}
```
### 取消任务
取消正在运行或排队的任务。
**请求：**
```
DELETE /api/v1/tasks/{task_id}
Authorization: Bearer your-secret-token-here
```
**响应 (200 OK)：**
```json
{
"message": "task canceled"
}
```
## Webhook 回调
如果配置了 `webhook_url`，API 会在任务完成或失败时向 webhook URL 发送 POST 请求。
**Webhook 请求：**
```
POST {webhook_url}
Content-Type: application/json
Authorization: Bearer your-secret-token-here
{
"task_id": "c9h8t1234abcd",
"status": "completed",
"title": "[tgfiles](file.pdf->local1:/downloads/file.pdf)",
"created_at": "2024-01-19T04:30:00Z",
"error": ""
}
```
## 使用示例
### 使用 cURL
**创建下载任务：**
```bash
curl -X POST http://localhost:8080/api/v1/tasks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret-token-here" \
-d '{
"telegram_url": "https://t.me/channel/123",
"user_id": 123456789,
"storage_name": "local1",
"dir_path": "/downloads"
}'
```
**获取任务状态：**
```bash
curl http://localhost:8080/api/v1/tasks/c9h8t1234abcd \
-H "Authorization: Bearer your-secret-token-here"
```
**列出所有任务：**
```bash
curl http://localhost:8080/api/v1/tasks \
-H "Authorization: Bearer your-secret-token-here"
```
**取消任务：**
```bash
curl -X DELETE http://localhost:8080/api/v1/tasks/c9h8t1234abcd \
-H "Authorization: Bearer your-secret-token-here"
```
### 使用 Python
```python
import requests
API_URL = "http://localhost:8080"
TOKEN = "your-secret-token-here"
HEADERS = {
"Authorization": f"Bearer {TOKEN}",
"Content-Type": "application/json"
}
# 创建下载任务
response = requests.post(
f"{API_URL}/api/v1/tasks",
headers=HEADERS,
json={
"telegram_url": "https://t.me/channel/123",
"user_id": 123456789,
"storage_name": "local1",
"dir_path": "/downloads"
}
)
task_id = response.json()["task_id"]
# 获取任务状态
response = requests.get(
f"{API_URL}/api/v1/tasks/{task_id}",
headers=HEADERS
)
status = response.json()
print(f"任务状态: {status['status']}")
```
## 安全建议
1. **生产环境始终使用强令牌**
2. **启用 IP 白名单** (`trusted_ips`) 限制访问
3. **生产环境使用 HTTPS**，通过反向代理（如 Nginx、Caddy）放置 API
4. **保护日志安全**，因为它们可能包含敏感信息
5. **验证用户权限** - 确保请求中的 `user_id` 对应于配置中的授权用户