API 调用文档

为开发者提供完整的 API 接口说明和调用示例

API 概述

AquaSource Bedrock Edition 版本信息 API 提供了获取 Minecraft Bedrock Edition 版本数据的 JSON 接口。

重要提示: 所有 API 请求都需要有效的合作伙伴令牌才能访问。请确保您已获得相应的访问权限。

基础信息

  • API 基础 URL: https://mc.mcscode.com/api/bedrock_versions.php
  • 请求方法: GET / POST
  • 响应格式: JSON
  • 字符编码: UTF-8
  • JSONP 支持: 是(通过 callback 参数)

功能特性

  • 🔐 安全的令牌认证机制
  • 📋 完整的版本列表获取
  • 🔍 强大的搜索和筛选功能
  • 📊 详细的统计信息
  • 🚀 高性能的分页支持
  • 🌐 跨域访问支持(CORS)
认证方式

API 支持三种令牌传递方式,按优先级排序:

1. Authorization 头部(推荐)

Authorization: Bearer YOUR_PARTNER_TOKEN

2. X-API-Token 头部

X-API-Token: YOUR_PARTNER_TOKEN

3. URL 参数

?token=YOUR_PARTNER_TOKEN
安全提示:
  • 令牌类型必须为"合作伙伴令牌"
  • 令牌状态必须为"活跃"
  • 令牌未过期(除非设置为永不过期)
  • 关联用户状态必须为"活跃"
  • 系统必须启用合作伙伴令牌功能

获取令牌

如需获取合作伙伴令牌,请:

  1. 联系系统管理员
  2. 说明您的使用场景和需求
  3. 管理员将在后台为您创建专用的合作伙伴令牌
API 接口列表
GET ?action=list

获取版本列表

获取 Bedrock Edition 版本的分页列表,支持搜索和筛选。

请求参数
参数名 类型 必需 默认值 说明
action string - 固定值:list
page int 1 页码
limit int 10 每页数量(最大100)
search string - 搜索关键词
status string - 状态筛选(活跃/禁用)
platform string - 平台筛选(Android/iOS/Windows)
version_type string - 版本类型(正式版/测试版)
请求示例
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://mc.mcscode.com/api/bedrock_versions.php?action=list&page=1&limit=10"
响应示例
{
  "success": true,
  "message": "获取版本列表成功",
  "data": {
    "versions": [
      {
        "id": 1,
        "version_name": "1.20.40",
        "version_code": "1.20.40.01",
        "platform": "Android",
        "version_type": "正式版",
        "status": "活跃",
        "release_date": "2023-10-24",
        "description": "Minecraft Bedrock Edition 1.20.40 版本",
        "views": 1250,
        "created_at": "2023-10-24 10:00:00"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 15,
      "total_records": 150,
      "per_page": 10,
      "has_next": true,
      "has_prev": false
    }
  },
  "timestamp": "2024-01-15 14:30:00"
}
GET ?action=detail&id={id}

获取版本详情

获取特定版本的详细信息,包括相关版本推荐。

请求参数
参数名 类型 必需 说明
action string 固定值:detail
id int 版本ID
请求示例
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://mc.mcscode.com/api/bedrock_versions.php?action=detail&id=1"
GET ?action=stats

获取统计信息

获取版本数据的统计信息,包括总数、平台分布、类型统计等。

请求示例
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://mc.mcscode.com/api/bedrock_versions.php?action=stats"
GET ?action=latest

获取最新版本

获取最新的 Bedrock Edition 版本信息。

请求参数
参数名 类型 必需 说明
action string 固定值:latest
platform string 平台筛选:Android | iOS | Windows
version_type string 版本类型:正式版 | 测试版
请求示例
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://mc.mcscode.com/api/bedrock_versions.php?action=latest&platform=Android"
GET ?action=search&search={keyword}

搜索版本

根据关键词搜索版本信息。

请求参数
参数名 类型 必需 说明
action string 固定值:search
search string 搜索关键词
page int 页码,默认为 1
limit int 每页数量,默认为 10,最大为 100
platform string 平台筛选:Android | iOS | Windows
version_type string 版本类型:正式版 | 测试版
请求示例
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://mc.mcscode.com/api/bedrock_versions.php?action=search&search=1.20"
代码示例

JavaScript (Fetch API)

// 获取版本列表
fetch('https://mc.mcscode.com/api/bedrock_versions.php?action=list&limit=20', {
    headers: {
        'Authorization': 'Bearer YOUR_PARTNER_TOKEN'
    }
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('版本列表:', data.data.versions);
        console.log('总数:', data.data.pagination.total_records);
    } else {
        console.error('错误:', data.error.message);
    }
})
.catch(error => {
    console.error('请求失败:', error);
});

JavaScript (jQuery AJAX)

// 获取版本详情
$.ajax({
    url: 'https://mc.mcscode.com/api/bedrock_versions.php',
    method: 'GET',
    headers: {
        'Authorization': 'Bearer YOUR_PARTNER_TOKEN'
    },
    data: {
        action: 'detail',
        id: 1
    },
    success: function(data) {
        if (data.success) {
            console.log('版本信息:', data.data);
        } else {
            alert('错误: ' + data.error.message);
        }
    },
    error: function(xhr, status, error) {
        alert('请求失败: ' + error);
    }
});

PHP (cURL)

<?php
// 获取版本列表
$token = 'YOUR_PARTNER_TOKEN';
$url = 'https://mc.mcscode.com/api/bedrock_versions.php?action=list&limit=10';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    if ($data['success']) {
        echo "获取到 " . count($data['data']['versions']) . " 个版本\n";
        foreach ($data['data']['versions'] as $version) {
            echo "版本: " . $version['version_name'] . "\n";
        }
    } else {
        echo "错误: " . $data['error']['message'] . "\n";
    }
} else {
    echo "HTTP错误: " . $httpCode . "\n";
}
?>

Python (requests)

import requests
import json

# 配置
token = 'YOUR_PARTNER_TOKEN'
base_url = 'https://mc.mcscode.com/api/bedrock_versions.php'

# 设置请求头
headers = {
    'Authorization': f'Bearer {token}'
}

# 获取版本列表
def get_versions(page=1, limit=10, search=''):
    params = {
        'action': 'list',
        'page': page,
        'limit': limit
    }
    if search:
        params['search'] = search
    
    try:
        response = requests.get(base_url, headers=headers, params=params)
        response.raise_for_status()
        
        data = response.json()
        if data['success']:
            return data['data']
        else:
            print(f"错误: {data['error']['message']}")
            return None
    except requests.exceptions.RequestException as e:
        print(f"请求失败: {e}")
        return None

# 使用示例
versions_data = get_versions(limit=20)
if versions_data:
    print(f"总共 {versions_data['pagination']['total_records']} 个版本")
    for version in versions_data['versions']:
        print(f"版本: {version['version_name']} - {version['platform']}")

JSONP 调用示例

// JSONP 回调函数
function handleVersions(data) {
    if (data.success) {
        console.log('版本数据:', data.data);
    } else {
        console.error('错误:', data.error.message);
    }
}

// 创建 JSONP 请求
function loadVersions() {
    const script = document.createElement('script');
    const token = 'YOUR_PARTNER_TOKEN';
    script.src = `https://mc.mcscode.com/api/bedrock_versions.php?action=list&token=${token}&callback=handleVersions`;
    document.head.appendChild(script);
}

// 调用
loadVersions();
在线测试

在这里您可以直接测试 API 接口,无需编写代码。

提示: 请先输入您的合作伙伴令牌,然后选择要测试的接口。

令牌设置

接口测试

GET 获取版本列表
GET 获取版本详情
GET 获取统计信息
GET 获取最新版本
错误处理

错误响应格式

当 API 请求失败时,会返回以下格式的错误响应:

{
  "success": false,
  "error": {
    "code": 401,
    "message": "无效的合作伙伴令牌或令牌已过期"
  },
  "timestamp": "2024-01-15 14:30:00"
}

常见错误代码

HTTP状态码 错误代码 错误信息 解决方案
401 401 无效的合作伙伴令牌或令牌已过期 检查令牌是否正确,是否已过期
400 400 无效的版本ID 确保提供的版本ID是有效的数字
400 400 不支持的操作类型 检查action参数是否正确
400 400 请提供搜索关键词 搜索接口必须提供search参数
404 404 版本不存在 检查版本ID是否存在
404 404 未找到符合条件的版本 调整搜索条件或筛选参数
500 500 服务器内部错误 联系技术支持

错误处理最佳实践

  • 检查 success 字段:始终检查响应中的 success 字段来判断请求是否成功
  • 处理网络错误:使用 try-catch 或 .catch() 处理网络请求异常
  • 用户友好提示:将技术错误信息转换为用户易懂的提示
  • 重试机制:对于临时性错误(如网络超时),可以实现重试机制
  • 日志记录:记录错误信息以便调试和监控

错误处理代码示例

// JavaScript 错误处理示例
async function fetchVersions() {
    try {
        const response = await fetch('https://mc.mcscode.com/api/bedrock_versions.php?action=list', {
            headers: {
                'Authorization': 'Bearer ' + token
            }
        });
        
        if (!response.ok) {
            throw new Error(`HTTP错误: ${response.status}`);
        }
        
        const data = await response.json();
        
        if (data.success) {
            // 处理成功响应
            console.log('版本数据:', data.data);
            return data.data;
        } else {
            // 处理API错误
            console.error('API错误:', data.error);
            
            // 根据错误代码提供用户友好的提示
            switch (data.error.code) {
                case 401:
                    alert('令牌无效或已过期,请重新获取令牌');
                    break;
                case 404:
                    alert('未找到相关数据');
                    break;
                case 500:
                    alert('服务器暂时不可用,请稍后重试');
                    break;
                default:
                    alert('请求失败: ' + data.error.message);
            }
            return null;
        }
    } catch (error) {
        // 处理网络错误
        console.error('网络错误:', error);
        alert('网络连接失败,请检查网络连接');
        return null;
    }
}