urldb/docs/api/overview.md

API 文档概览

概述

老九网盘资源数据库提供了一套完整的 RESTful API 接口，支持资源管理、搜索、热门剧获取等功能。所有 API 都需要进行认证，使用 API Token 进行身份验证。

基础信息

• 基础URL: http://localhost:8080/api
• 认证方式: API Token
• 数据格式: JSON
• 字符编码: UTF-8

认证说明

认证方式

所有 API 都需要提供 API Token 进行认证，支持两种方式：

1. 请求头方式（推荐）

   X-API-Token: your_token_here
   

2. 查询参数方式

   ?api_token=your_token_here
   

获取 Token

请联系管理员在系统配置中设置 API Token。

API 接口列表

1. 单个添加资源

接口描述: 添加单个资源到待处理列表

请求信息:

• 方法: POST
• 路径: /api/public/resources/add
• 认证: 必需

请求参数:

{
  "title": "资源标题",
  "description": "资源描述",
  "url": "资源链接",
  "category": "分类名称",
  "tags": "标签1,标签2",
  "img": "封面图片链接",
  "source": "数据来源",
  "extra": "额外信息"
}

响应示例:

{
  "success": true,
  "message": "资源添加成功，已进入待处理列表",
  "data": {
    "id": 123
  },
  "code": 200
}

2. 批量添加资源

接口描述: 批量添加多个资源到待处理列表

请求信息:

• 方法: POST
• 路径: /api/public/resources/batch-add
• 认证: 必需

请求参数:

{
  "resources": [
    {
      "title": "资源1",
      "url": "链接1",
      "description": "描述1"
    },
    {
      "title": "资源2", 
      "url": "链接2",
      "description": "描述2"
    }
  ]
}

响应示例:

{
  "success": true,
  "message": "批量添加成功，共添加 2 个资源",
  "data": {
    "created_count": 2,
    "created_ids": [123, 124]
  },
  "code": 200
}

3. 资源搜索

接口描述: 搜索资源，支持关键词、标签、分类过滤

请求信息:

• 方法: GET
• 路径: /api/public/resources/search
• 认证: 必需

查询参数:

• keyword - 搜索关键词
• tag - 标签过滤
• category - 分类过滤
• page - 页码（默认1）
• page_size - 每页数量（默认20，最大100）

响应示例:

{
  "success": true,
  "message": "搜索成功",
  "data": {
    "resources": [
      {
        "id": 1,
        "title": "资源标题",
        "url": "资源链接",
        "description": "资源描述",
        "view_count": 100,
        "created_at": "2024-12-19 10:00:00",
        "updated_at": "2024-12-19 10:00:00"
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20
  },
  "code": 200
}

4. 热门剧列表

接口描述: 获取热门剧列表，支持分页

请求信息:

• 方法: GET
• 路径: /api/public/hot-dramas
• 认证: 必需

查询参数:

• page - 页码（默认1）
• page_size - 每页数量（默认20，最大100）

响应示例:

{
  "success": true,
  "message": "获取热门剧成功",
  "data": {
    "hot_dramas": [
      {
        "id": 1,
        "title": "剧名",
        "description": "剧集描述",
        "img": "封面图片",
        "url": "详情链接",
        "rating": 8.5,
        "year": "2024",
        "region": "中国大陆",
        "genres": "剧情,悬疑",
        "category": "电视剧",
        "created_at": "2024-12-19 10:00:00",
        "updated_at": "2024-12-19 10:00:00"
      }
    ],
    "total": 20,
    "page": 1,
    "page_size": 20
  },
  "code": 200
}

错误码说明

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
401	认证失败（Token无效或缺失）
500	服务器内部错误
503	系统维护中或API Token未配置

响应格式

所有 API 响应都遵循统一的格式：

{
  "success": true/false,
  "message": "响应消息",
  "data": {}, // 响应数据
  "code": 200 // 状态码
}

使用示例

cURL 示例

# 设置API Token
API_TOKEN="your_api_token_here"

# 单个添加资源
curl -X POST "http://localhost:8080/api/public/resources/add" \
  -H "Content-Type: application/json" \
  -H "X-API-Token: $API_TOKEN" \
  -d '{
    "title": "测试资源",
    "url": "https://example.com/resource",
    "description": "测试描述"
  }'

# 搜索资源
curl -X GET "http://localhost:8080/api/public/resources/search?keyword=测试" \
  -H "X-API-Token: $API_TOKEN"

# 获取热门剧
curl -X GET "http://localhost:8080/api/public/hot-dramas?page=1&page_size=5" \
  -H "X-API-Token: $API_TOKEN"

JavaScript 示例

const API_TOKEN = 'your_api_token_here';
const BASE_URL = 'http://localhost:8080/api';

// 添加资源
async function addResource(resourceData) {
  const response = await fetch(`${BASE_URL}/public/resources/add`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Token': API_TOKEN
    },
    body: JSON.stringify(resourceData)
  });
  return await response.json();
}

// 搜索资源
async function searchResources(keyword, page = 1) {
  const response = await fetch(
    `${BASE_URL}/public/resources/search?keyword=${encodeURIComponent(keyword)}&page=${page}`,
    {
      headers: {
        'X-API-Token': API_TOKEN
      }
    }
  );
  return await response.json();
}

// 获取热门剧
async function getHotDramas(page = 1, pageSize = 20) {
  const response = await fetch(
    `${BASE_URL}/public/hot-dramas?page=${page}&page_size=${pageSize}`,
    {
      headers: {
        'X-API-Token': API_TOKEN
      }
    }
  );
  return await response.json();
}

Python 示例

import requests

API_TOKEN = 'your_api_token_here'
BASE_URL = 'http://localhost:8080/api'

headers = {
    'X-API-Token': API_TOKEN,
    'Content-Type': 'application/json'
}

# 添加资源
def add_resource(resource_data):
    response = requests.post(
        f'{BASE_URL}/public/resources/add',
        headers=headers,
        json=resource_data
    )
    return response.json()

# 搜索资源
def search_resources(keyword, page=1):
    params = {
        'keyword': keyword,
        'page': page
    }
    response = requests.get(
        f'{BASE_URL}/public/resources/search',
        headers={'X-API-Token': API_TOKEN},
        params=params
    )
    return response.json()

# 获取热门剧
def get_hot_dramas(page=1, page_size=20):
    params = {
        'page': page,
        'page_size': page_size
    }
    response = requests.get(
        f'{BASE_URL}/public/hot-dramas',
        headers={'X-API-Token': API_TOKEN},
        params=params
    )
    return response.json()

最佳实践

1. 错误处理

始终检查响应的 success 字段和 HTTP 状态码：

const response = await fetch(url, options);
const data = await response.json();

if (!response.ok || !data.success) {
  console.error('API调用失败:', data.message);
  // 处理错误
}

2. 分页处理

对于支持分页的接口，建议实现分页逻辑：

async function getAllResources(keyword) {
  let allResources = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await searchResources(keyword, page);
    if (response.success) {
      allResources.push(...response.data.resources);
      hasMore = response.data.resources.length > 0;
      page++;
    } else {
      break;
    }
  }
  
  return allResources;
}

3. 请求频率限制

避免过于频繁的 API 调用，建议实现请求间隔：

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function searchWithDelay(keyword) {
  const result = await searchResources(keyword);
  await delay(1000); // 等待1秒
  return result;
}

注意事项

1. Token 安全: 请妥善保管您的 API Token，不要泄露给他人
2. 请求限制: 避免过于频繁的请求，以免影响系统性能
3. 数据格式: 确保请求数据格式正确，特别是 JSON 格式
4. 错误处理: 始终实现适当的错误处理机制
5. 版本兼容: API 可能会进行版本更新，请关注更新通知

技术支持

如果您在使用 API 过程中遇到问题，请：

1. 检查 API Token 是否正确
2. 确认请求格式是否符合要求
3. 查看错误响应中的详细信息
4. 联系技术支持团队

---

注意: 本站内容由网络爬虫自动抓取。本站不储存、复制、传播任何文件，仅作个人公益学习，请在获取后24小时内删除！