基本信息

速率限制

目前，对于单个 IP：每 10 秒 500 个请求。

HTTP 状态码

BigONE 开发者 API 遵循 RFC 标准。

响应结构

成功

{
	"code": 0,
	"message": "代码描述",
	"data": {},
}

分页

{
	"code": 0,
	"message": "代码描述",
	"data": {},
	"page_token":"dxvf"
}

错误

{
	"code": 10005,
	"message": "内部错误",
}

API 认证

本文档提供了 BigONE 开发者 API 的认证指南。

BigONE 开发者 API 分为公共 API 和私有 API。对于私有 API 访问，开发者必须在请求头中提供一个 token，以便 BigONE 验证用户身份：

curl "https://API_SERVER/viewer/accounts" \
     -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiT3BlbkFQSSIsInN1YiI6ImNlZTg4YWIwYmM2OTQzNTc4NGI3ZGIwNTQ1ZTg1NjQ3Iiwibm9uY2UiOjE1Mjc2NjUyNjIxNjgzOTEwMDB9.YNpae4v_-OU7h2sknRPa3XPhDcC3p-To1WxbWV4Vpro'

开发者在访问私有 API 时，需要在请求中包含 Authorization 头部。该头部的值必须遵循 Bearer {YOUR_TOKEN} 的格式。

如何获取 API 密钥和 API 密钥 Secret

开发者可以通过 BigONE 设置页面 生成 API 密钥和 API Secret。

设置您的 Token

BigONE API 使用 JSON Web Tokens (JWT) 来确保请求的授权。

您需要使用与您编程语言兼容的 JWT 库，该库支持 HS256 算法和 MapClaim 声明类型。

请注意，不要使用 Base64 编码您的签名；这样做会导致 token 无效。

JWT 头部要求

确保您的 JWT 头部符合以下规格：

JWT 头部声明	类型	值
alg	string	"HS256"
typ	string	"JWT"

JWT 负载要求

您的 JWT 必须使用 API Secret 签名，并且其负载应符合以下规格：

JWT 负载声明	类型	值
type	string	必需。值必须是 OpenAPIV2。
sub	string	必需。您的 API 密钥。
nonce	string	必需。必须是转换为字符串的时间戳。nonce 与当前时间戳之间的差异必须小于 recv_window 设置的秒数。该时间戳以纳秒为单位表示，自 UNIX 纪元以来的时间，例如：1527665262168391000。
recv_window	string	可选。指定允许的时间戳偏移量（单位：秒）。默认值为 30。

示例

假设您的 API 密钥是 765fc50d-39e0-11f0-9669-5a69d7ba6f46，API Secret 是 testsecret。

JWT 头部

{
  "typ": "JWT",
  "alg": "HS256"
}

通常，JWT 头部 会由 JWT SDK 自动设置。

JWT 负载

{
  "type": "OpenAPIV2",
  "sub": "765fc50d-39e0-11f0-9669-5a69d7ba6f46",
  "nonce": "1527665262168391000"
}

使用您的 API Secret 签名：

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoiT3BlbkFQSVYyIiwic3ViIjoiY2VlODhhYjBiYzY5NDM1Nzg0YjdkYjA1NDVlODU2NDciLCJub25jZSI6MTUyNzY2NTI2MjE2ODM5MTAwMH0.cJ_uPmDeIxEPbKb_Xi0YuCflt_kgok5lryPwDG-jrsM

您可以在 调试器 中验证编码后的签名。

这是一个生成 JWT Token 的 Python 脚本示例，使用 HS256 算法。此脚本假设您已经准备好了 API_KEY 和 API_SECRET，因为这些是生成 token 时必需的。nonce 值是一个纳秒时间戳。

import jwt
import time

# 您的 API 密钥和 API Secret 来自 BigONE 设置页面
API_KEY = 'your_api_key_here'
API_SECRET = 'your_api_secret_here'

# 生成 nonce：当前的纳秒时间戳
nonce = int(time.time() * 1e9)

# JWT 负载
payload = {
    "type": "OpenAPIV2",
    "sub": API_KEY,
    "nonce": str(nonce),
}

# 使用 HS256 算法对 JWT 进行编码
token = jwt.encode(payload, API_SECRET, algorithm="HS256")

printf("Authorization: Bearer {token}")