Sui项目Faucet API版本升级指南：从v1迁移到v2

Sui区块链项目即将对其Faucet服务API进行重要版本升级，原有的v1版本API将于2025年4月18日正式弃用，全面转向v2版本。这一变更将影响所有使用Sui测试网水龙头服务的开发者。

API变更详情

本次升级主要涉及两个核心端点：

1. gas请求端点：

   • 原v1端点/v1/gas和/gas将统一迁移至/v2/gas
   • 响应数据结构有重大调整

2. 状态查询端点：

   • 原/v1/status端点将被移除
   • 新版本中，状态信息将直接通过/v2/gas的响应返回

新版响应数据结构

v2 API采用了更加结构化的响应格式，分为成功和失败两种情况：

成功响应示例

{
  "status": "Success",
  "coins_sent": [
    {
      "amount": 5500000000,
      "id": "0xac8b8afbc9074465bf799d0f590e17176b7a05514b9434b338e38f49be14d574",
      "transferTxDigest": "DSHGocWx57BtYDE5Xv4AefeRBBMizPb3LTqRMegx14Ym"
    }
  ]
}

主要变更点：

• 字段名从coin_sent改为coins_sent
• 支持返回多个代币信息（数组结构）
• 包含更完整的交易元数据

失败响应示例

{
  "status": {
    "Failure": {
      "ErrorType": "message"
    }
  },
  "coins_sent": null
}

错误类型(ErrorType)包括：

• Internal：服务器内部错误
• InvalidUserAgent：无效的用户代理
• TooManyRequests：请求过于频繁
• MissingTurnstileTokenHeader：缺少必要的安全令牌

HTTP状态码规范

新版API严格遵循RESTful设计原则，使用标准HTTP状态码：

• 200 OK：请求成功处理
• 400 Bad Request：客户端请求错误（无效UA或缺少令牌）
• 429 Too Many Requests：请求频率过高
• 500 Internal Server Error：服务器内部错误

迁移建议

1. 及时更新端点URL：将所有v1端点替换为对应的v2版本
2. 调整响应处理逻辑：新版数据结构变化较大，特别是成功情况下返回的是代币数组
3. 错误处理优化：利用标准HTTP状态码和详细的错误类型进行更精准的错误处理
4. 移除状态查询：不再需要单独查询状态，结果直接包含在gas请求响应中

技术背景

Faucet服务是区块链测试网的核心组件，为开发者提供测试用代币。Sui此次API升级主要出于以下考虑：

1. 安全性增强：通过Turnstile令牌机制防止滥用
2. 性能优化：简化API结构，减少不必要的请求
3. 功能扩展：支持批量代币返回，为未来功能预留空间
4. 标准化：遵循行业最佳实践，使用标准HTTP语义

建议所有集成Sui测试网的开发者尽快完成API迁移，以确保在v1停用后服务不受影响。