Alaikis Documents

Appearance

API请求与验证指南 ​

基础请求格式 ​

所有API请求必须使用HTTPS协议，基本格式如下：

http
POST /api/v1/endpoint HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer your_access_token
X-Timestamp: 1630000000000
X-Nonce: abcdef123456
X-Signature: signature_value

{
  "param1": "value1",
  "param2": "value2"
}

认证机制 ​

1. 访问令牌认证 ​

  • 获取访问令牌：通过OAuth2.0授权流程获取
  • 令牌有效期：2小时
  • 刷新令牌：使用refresh_token获取新access_token

2. 签名验证 ​

每个请求必须包含以下签名头：

  • X-Timestamp: 请求时间戳(毫秒)
  • X-Nonce: 随机字符串(6-32位)
  • X-Signature: 请求签名

签名生成算法：

javascript
const crypto = require('crypto');

function generateSignature(secret, params) {
  const sortedParams = Object.keys(params).sort().map(k => `${k}=${params[k]}`).join('&');
  return crypto.createHmac('sha256', secret).update(sortedParams).digest('hex');
}

错误处理 ​

常见错误码 ​

错误码说明
400请求参数错误
401认证失败
403权限不足
404资源不存在
429请求频率限制
500服务器内部错误

错误响应格式 ​

json
{
  "success": false,
  "error": {
    "code": 401,
    "message": "Invalid access token",
    "details": "Token expired"
  }
}

最佳实践 ​

  1. 请求频率控制：单个API不超过10次/秒
  2. 错误重试：对5xx错误最多重试3次
  3. 参数验证：客户端应预先验证必填参数
  4. 安全存储：妥善保管API密钥和访问令牌

常见问题 ​

Q: 签名验证失败怎么办？ A: 检查时间戳是否在服务器时间±5分钟内，nonce是否唯一

Q: 如何获取API密钥？ A: 登录开发者控制台，在"API管理"中创建应用获取

Q: 请求被限速如何处理？ A: 降低请求频率或联系我们提高配额