数据服务平台 API 文档

统一的数据抓取与聚合服务接口，支持 24+ 数据源、实时搜索。通过 API Key 认证即可调用。

概述

本服务提供统一的数据搜索接口，底层对接了多个公开数据源（新闻、学术论文、政策文件、论坛讨论等），开发者无需逐个对接各平台 API。

基本信息

基础地址：http://your-server:8900
所有请求和响应均使用 JSON 格式
请求头需设置 Content-Type: application/json
数据接口（/api/v1/）需携带 API Key 认证
管理接口（/api/）需携带 JWT Token 认证

使用流程

注册账号并获取 API Key
查看可用数据源列表
查询数据源支持的参数
调用搜索接口获取数据

认证方式

1. API Key 认证（数据接口）

所有 /api/v1/* 接口使用 API Key 认证。通过以下两种方式传递：

# 方式一：请求头（推荐）
X-API-Key: your_api_key_here

# 方式二：URL 参数
GET /api/v1/sources?api_key=your_api_key_here

2. JWT Token 认证（管理接口）

所有 /api/*（非 v1）接口使用 Bearer Token 认证：

Authorization: Bearer your_jwt_token_here

Token 通过登录接口获取，有效期 24 小时。

注册成功后系统会自动分配一个 API Key。你也可以在管理界面创建多个密钥。

错误处理

所有接口的响应中都包含 ok 字段表示是否成功：

// 成功
{"ok": true, "data": ...}

// 失败
{"ok": false, "error": "错误描述信息"}

HTTP 状态码

状态码	含义
200	请求成功
400	参数错误
401	未认证或 Token/Key 无效
403	无权限（如账号被禁用）
409	资源冲突（如用户名已存在）
429	超出每日调用配额

单源搜索

POST /api/v1/search

API Key

向指定数据源发起实时搜索请求，返回搜索结果。所有结果不会存入数据库。

请求参数

字段	类型	必填	说明
`source_key`	string	是	数据源标识，如 "arxiv", "hackernews"
`keyword`	string	是	搜索关键词
`params`	object	否	额外查询参数，各数据源不同（见参数查询接口）

请求示例

# 基础搜索
curl -X POST http://localhost:8900/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "source_key": "arxiv",
    "keyword": "machine learning",
    "params": {"max_results": 5}
  }'

响应示例

{
  "ok": true,
  "source_key": "arxiv",
  "keyword": "machine learning",
  "result_count": 5,
  "duration_ms": 1234,
  "items": [
    {
      "title": "论文标题",
      "url": "https://arxiv.org/abs/...",
      "summary": "摘要内容...",
      "published": "2024-01-01"
    }
  ]
}

多源搜索

POST /api/v1/search/multi

API Key

同时向多个数据源发起搜索，返回聚合结果。最多同时查询 10 个数据源。

请求参数

字段	类型	必填	说明
`source_keys`	string[]	是	数据源标识数组，最多 10 个
`keyword`	string	是	搜索关键词
`params`	object	否	额外查询参数（应用到所有源）

请求示例

curl -X POST http://localhost:8900/api/v1/search/multi \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "source_keys": ["arxiv", "hackernews", "wikipedia"],
    "keyword": "人工智能",
    "params": {"max_results": 3}
  }'

响应示例

{
  "ok": true,
  "keyword": "人工智能",
  "total_items": 9,
  "results": [
    {"ok": true, "source_key": "arxiv", "result_count": 3, ...},
    {"ok": true, "source_key": "hackernews", "result_count": 3, ...},
    {"ok": true, "source_key": "wikipedia", "result_count": 3, ...}
  ]
}

数据源列表

GET /api/v1/sources

API Key

获取所有已启用的数据源列表及其基本信息。

响应字段

字段	类型	说明
`source_key`	string	数据源唯一标识
`name`	string	显示名称
`source_type`	string	类型（web_search/news/academic/policy/forum）
`base_url`	string	数据源网址
`auth_required`	boolean	是否需要配置额外凭证
`default_params`	object	默认查询参数

请求示例

curl http://localhost:8900/api/v1/sources \
  -H "X-API-Key: your_api_key"

查询参数说明

GET /api/v1/sources/{source_key}/params

API Key

获取指定数据源的函数签名参数说明，帮助你了解可以传入哪些查询参数。

路径参数

参数	说明
`source_key`	数据源标识，如 "arxiv"

响应示例

{
  "ok": true,
  "source_key": "arxiv",
  "function": "fetch_arxiv",
  "accepted_params": [
    {"name": "max_results", "type": "int", "default": 10, "required": false},
    {"name": "sort_by", "type": "str", "default": "relevance", "required": false}
  ],
  "default_values": {"max_results": 10}
}

每个数据源支持的参数不同。搜索时，在 params 字段中传入的参数会自动过滤为目标函数支持的参数，不支持的参数会被静默忽略。

用户注册

POST /api/auth/register

无需认证

注册新用户，注册成功后自动分配 JWT Token 和 API Key。

请求参数

字段	类型	必填	说明
`username`	string	是	用户名，至少 3 个字符
`password`	string	是	密码，至少 6 个字符
`email`	string	否	邮箱地址

响应示例

{
  "ok": true,
  "user": {"id": 2, "username": "dev1", "role": "user"},
  "token": "eyJhbGci...",
  "api_key": "ds_a1b2c3d4..."
}

请妥善保管返回的 API Key，系统不会再次显示完整密钥。

用户登录

POST /api/auth/login

无需认证

登录并获取 JWT Token，用于管理接口的身份认证。

请求参数

字段	类型	必填	说明
`username`	string	是	用户名
`password`	string	是	密码

响应示例

{
  "ok": true,
  "user": {"id": 1, "username": "root", "role": "admin"},
  "token": "eyJhbGci..."
}

当前用户信息

GET /api/auth/me

JWT Token

获取当前登录用户的详细信息和 API Key 列表。

响应示例

{
  "ok": true,
  "user": {
    "id": 1,
    "username": "root",
    "email": "admin@dataservice.local",
    "role": "admin"
  },
  "api_keys": [
    {
      "id": 1,
      "key_name": "default",
      "api_key": "ds_...",
      "is_active": 1,
      "calls_today": 42,
      "calls_total": 1580,
      "rate_limit": 1000
    }
  ]
}

创建 API 密钥

POST /api/keys/create

JWT Token

为当前用户创建一个新的 API Key。每个用户可拥有多个密钥。

请求参数

字段	类型	必填	说明
`name`	string	否	密钥名称，默认为 "default"

其他密钥操作

操作	方法	路径	参数
禁用密钥	POST	`/api/keys/revoke`	`{"key_id": 123}`

测试数据源

POST /api/sources/{source_key}/test

JWT Token

执行一次真实的数据源搜索测试，可自由传入任意查询参数。结果不存入数据库。

请求参数

字段	类型	必填	说明
`keyword`	string	是	搜索关键词
`params`	object	否	自定义查询参数（key-value 格式），不支持的参数会被自动忽略

请求示例

curl -X POST http://localhost:8900/api/sources/arxiv/test \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "keyword": "deep learning",
    "params": {
      "max_results": 3,
      "sort_by": "submittedDate"
    }
  }'

健康检测

POST /api/sources/{source_key}/health

JWT Token

对指定数据源执行最小化搜索请求以验证其连通性和响应速度。

响应示例

// 正常
{"ok": true, "status": "healthy", "latency_ms": 856, "sample_count": 1}

// 异常
{"ok": true, "status": "unhealthy", "error": "connection timeout"}

Python 调用示例

# pip install requests
import requests

API_BASE = "http://localhost:8900"
API_KEY = "your_api_key_here"

headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# 查看可用数据源
sources = requests.get(f"{API_BASE}/api/v1/sources", headers=headers).json()
print(f"共 {len(sources['sources'])} 个数据源可用")

# 查看 arxiv 支持的参数
params_info = requests.get(f"{API_BASE}/api/v1/sources/arxiv/params", headers=headers).json()
print("支持参数:", [p["name"] for p in params_info["accepted_params"]])

# 搜索 arxiv
result = requests.post(f"{API_BASE}/api/v1/search", headers=headers, json={
    "source_key": "arxiv",
    "keyword": "transformer attention mechanism",
    "params": {"max_results": 5}
}).json()

if result["ok"]:
    print(f"找到 {result['result_count']} 条结果, 耗时 {result['duration_ms']}ms")
    for item in result["items"]:
        print(f"  - {item.get('title', 'N/A')}")

# 多源搜索
multi = requests.post(f"{API_BASE}/api/v1/search/multi", headers=headers, json={
    "source_keys": ["arxiv", "hackernews", "wikipedia"],
    "keyword": "GPT-4",
}).json()
print(f"多源搜索共 {multi['total_items']} 条结果")

数据服务平台 v1.0.0 | 如有问题请联系管理员