Ruanm API 文档
开发者参考指南

简介

欢迎使用 Ruanm API！本文档将帮助您了解如何使用我们的 API 来构建功能丰富的应用程序。

基础 URL

http://localhost:3000/api

认证授权

大多数 API 端点都需要认证。我们使用 JWT (JSON Web Tokens) 进行认证。

获取访问令牌

要获取访问令牌，您需要先注册开发者账号并获得 API 密钥。

请求

POST /api/auth/token
Content-Type: application/json

{
  "api_key": "your_api_key_here"
}

响应

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

使用访问令牌

获取令牌后，在后续请求的 Authorization 头中包含它：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

用户管理

获取用户信息

获取指定用户的公开信息。

请求

GET /api/users/{userId}
Authorization: Bearer YOUR_ACCESS_TOKEN

响应

{
  "success": true,
  "data": {
    "id": "123456",
    "username": "example_user",
    "email": "user@example.com",
    "avatar": "https://example.com/avatar.jpg",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

更新用户信息

更新当前认证用户的个人信息。

请求

PUT /api/users/{userId}
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "username": "new_username",
  "email": "new_email@example.com"
}

响应

{
  "success": true,
  "data": {
    "id": "123456",
    "username": "new_username",
    "email": "new_email@example.com",
    "avatar": "https://example.com/avatar.jpg",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-02T00:00:00Z"
  }
}

游戏中心

获取游戏列表

获取所有可用游戏的列表。

请求

GET /api/games
Authorization: Bearer YOUR_ACCESS_TOKEN

响应

{
  "success": true,
  "data": [
    {
      "id": "game1",
      "name": "超级马里奥",
      "description": "经典平台跳跃游戏",
      "thumbnail": "https://example.com/mario.jpg",
      "category": "platformer"
    },
    {
      "id": "game2",
      "name": "俄罗斯方块",
      "description": "经典的益智游戏",
      "thumbnail": "https://example.com/tetris.jpg",
      "category": "puzzle"
    }
  ]
}

产品中心

获取产品列表

获取所有可用产品的列表。

请求

GET /api/products
Authorization: Bearer YOUR_ACCESS_TOKEN

响应

{
  "success": true,
  "data": [
    {
      "id": "product1",
      "name": "Ruanm 屏保程序",
      "description": "个性化您的Windows体验",
      "thumbnail": "https://example.com/screensaver.jpg",
      "price": 0
    },
    {
      "id": "product2",
      "name": "Ruanm Studio",
      "description": "强大的软件开发工具包",
      "thumbnail": "https://example.com/studio.jpg",
      "price": 0
    }
  ]
}

错误处理

当 API 请求出现问题时，我们会返回标准的错误响应格式。

错误响应格式

{
  "success": false,
  "error": "错误信息描述",
  "code": "ERROR_CODE"
}

常见错误代码

速率限制

为了保证服务质量，API 对请求频率有所限制。

查看速率限制信息

每个响应都包含速率限制相关信息的头部：

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

如果超过速率限制，API 将返回 429 状态码和相应的错误信息。

代码示例

以下是一些使用 Ruanm API 的实用代码示例。

JavaScript 示例

使用 JavaScript 获取用户信息：

// 获取访问令牌
async function getAccessToken(apiKey) {
  const response = await fetch('http://localhost:3000/api/auth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ api_key: apiKey })
  });
  
  const data = await response.json();
  return data.token;
}

// 获取用户信息
async function getUserInfo(userId, token) {
  const response = await fetch(`http://localhost:3000/api/users/${userId}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  
  const data = await response.json();
  return data;
}

// 使用示例
(async () => {
  try {
    const token = await getAccessToken('your_api_key_here');
    const userInfo = await getUserInfo('123456', token);
    console.log(userInfo);
  } catch (error) {
    console.error('Error:', error);
  }
})();

Python 示例

使用 Python 获取游戏列表：

import requests

def get_access_token(api_key):
    url = "http://localhost:3000/api/auth/token"
    payload = {"api_key": api_key}
    response = requests.post(url, json=payload)
    return response.json()["token"]

def get_games(token):
    url = "http://localhost:3000/api/games"
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(url, headers=headers)
    return response.json()

# 使用示例
try:
    token = get_access_token("your_api_key_here")
    games = get_games(token)
    print(games)
except Exception as e:
    print(f"Error: {e}")