Bountysource REST API完全参考：一文掌握v0/v1/v2版本化、JWT鉴权与接口实战-平芜编程栈

Bountysource REST API完全参考：一文掌握v0/v1/v2版本化、JWT鉴权与接口实战

【免费下载链接】coreBountysource is the funding platform for open-source software.项目地址: https://gitcode.com/gh_mirrors/core112/core

Bountysource 是面向开源软件的悬赏资助平台，允许出资人在 Issue 上挂出赏金、邀请开发者认领开发。本文从新手视角带你完整走通 Bountysource REST API：v0/v1/v2 版本化差异、JWT 风格访问令牌鉴权、分页与错误码，以及 3 条命令完成接口实战。

三个 API 版本怎么选：v0、v1、v2 一图看懂

Bountysource 使用api-versionsgem（见Gemfile）在路由文件中将接口划分为三个版本：

版本	路径	定位	典型资源
v1	根路径（默认版本）	当前主力版本	用户、团队、悬赏、认领、众筹
v2	`/v2/`	新版能力	Issue 搜索、悬赏汇总、Pact、钱包
v0	`/v0/admin/`	仅平台管理员	统计报表、同步、退款、提现

💡新手建议：常规读操作用v1，Issue 检索等较新能力用v2，千万不要碰/v0/admin/。此外还可以用 vendor string 通过Accept头指定版本，例如application/vnd.bountysource+json; version=2。API 域名由config/application.rb中的环境变量BOUNTYSOURCE_API_URL统一配置，仅接受 HTTPS 请求。

JWT 风格令牌鉴权：两步搞定

Bountysource 不依赖会话 Cookie，而是使用三段式签名访问令牌（用户ID.时间戳.SHA1签名），结构上与 JWT 一致，实现见app/models/access_token.rb：

获取令牌📌：登录后系统为账户签发专属令牌，有效期 30 天，到期自动失效；
传递令牌✅：两种传法任选其一
- 查询参数：GET /v2/issues?access_token=你的令牌
- 请求头：Authorization: token 你的令牌

所有请求在app/controllers/api/base_controller.rb的current_user中统一拦截解析；写操作（创建悬赏、提交认领等）会先经过require_auth校验，令牌缺失或无效直接返回401 Unauthorized。

请求必备知识：CORS、分页与常见错误码

跨域友好🌐：所有 API 响应都带Access-Control-Allow-Origin: *及完整的 CORS 头，浏览器前端可直接调用；响应同时设置 no-cache 防止缓存脏数据。

v2 统一分页📄：传page和per_page两个参数即可（默认 25 条/页，上限 25 条，见app/helpers/api/v2/pagination_helper.rb）。多页结果会额外返回三个响应头，方便前端直接翻页：

Link：rel=next / prev / first / last完整翻页链接
Total-Pages：总页数
Total-Items：总条数

常见错误码速查：

状态码	含义	处理建议
401	未授权	检查令牌是否存在、是否过期
404	资源不存在	检查 ID 与路径前缀
422	校验失败/缺少必填参数	阅读`error`字段，错误信息会列出缺失参数名
406	Accept 头不受支持	改用`application/vnd.bountysource+json; version=2`

新手实战：3 条命令查 Issue 与悬赏

上图正是 API 管理的数据模型：在 GitHub Issue 上挂载 $300 悬赏、打上has_bounty标签。最常被调用的 3 个接口如下：

1️⃣ 搜索 Issue（v2，支持关键词与嵌套返回）：

curl "https://api.bountysource.com/v2/issues?search=github&include_tracker=true&page=1"

2️⃣ 获取 Issue 详情（v2，include_tracker可带出所属项目信息）：

curl "https://api.bountysource.com/v2/issues/123?include_tracker=true"

3️⃣ 查询悬赏列表（v2，仅返回未退款的悬赏，include_owner附带出资人）：

curl "https://api.bountysource.com/v2/bounties?include_owner=true"

需要写操作时加上令牌即可（查询参数或Authorization头）。这两个控制器的完整参数定义见app/controllers/api/v2/issues_controller.rb与app/controllers/api/v2/bounties_controller.rb。

新手必看的 5 条最佳实践

📌 一律使用HTTPS，非加密请求会被强制重定向；
✅ 善用include_*参数（include_tracker、include_team、include_counts等）控制嵌套返回，避免二次请求；
🔄 令牌 30 天过期，长期运行的客户端要预留刷新逻辑；
🧾 翻页时读取Link/Total-Pages响应头，不要硬编码页码；
🚫/v0/admin/下的接口仅限平台运维，第三方集成请勿调用。