REST API
REST API 是按 REST 风格(Representational State Transfer)构建的 API:每个数据集都是一个有独立 URL 的资源,由 HTTP 方法决定操作,服务器在请求之间不保存客户端状态。这一风格由 Roy Fielding 在 2000 年的博士论文中提出。
请求拆解
请求所有交易所的 BTC 资金费率:
curl "https://api.genesisarbitrage.com/v1/funding/rates?coin=BTC" \
-H "X-API-Key: $GENESIS_API_KEY"
| 部分 | 值 | 含义 |
|---|---|---|
| 方法 | GET | 读取数据 |
| 基础 URL | https://api.genesisarbitrage.com/v1 | 服务器和 API 版本 |
| 资源 | /funding/rates | 交易所资金费率 |
| 参数 | coin=BTC | 仅 BTC |
| 请求头 | X-API-Key | 客户端密钥 |
响应是 JSON:data 中是 BTC 及交易所列表,每家交易所都有按资金费率结算周期计的费率(funding_pct)和折算为 8 小时的费率(funding_8h_pct)。不带 coin 时,同一资源返回所有币种。字段说明见资金费率一节。
方法与状态
方法告诉服务器对资源做什么。方法的语义由 HTTP 标准 RFC 9110 规定:
GET:获取数据;该方法是安全的,不会改变服务器上的任何内容;POST:提交数据供处理;Binance 用它下单(POST /api/v3/order);PUT:创建或替换资源;DELETE:删除;Binance 用它撤单(DELETE /api/v3/order)。
Genesis API 只提供数据,所以它的所有接口都是 GET。
无状态(stateless)意味着每个请求都携带所需的一切:密钥、资源、筛选条件。服务器不记得之前的调用,GET 也不改变任何内容,因此在超时或 503 之后可以重复请求:结果只取决于请求本身和当前数据。为避免重复下载未变化的数据,Genesis API 会发送 ETag:带 If-None-Match 的请求在数据没有变化时会收到 304。
REST 与 WebSocket
| REST API | WebSocket | |
|---|---|---|
| 交互方式 | 请求与响应 | 双向消息流 |
| 由谁发起 | 客户端 | 连接建立后任一方 |
| 适用场景 | 快照、筛选、历史数据 | 成交和订单簿推送 |
| 在 Genesis API 中 | 每个接口 | 无 |
使用 REST 时,通过轮询获取更新:程序按间隔重复请求。Genesis API 每隔 meta.freshness_sec 秒刷新一次输出,从 Trial 的 60 秒到 Max 的 5 秒,所以更频繁地轮询没有任何收益。
另见:接口、WebSocket、响应格式、课程:用 HTTP、请求头和 JSON 发出你的第一个 API 请求。
常见问题
REST API 与一般意义上的 API 有什么不同?
API 是程序之间相互通信所用的任何一套规则。REST API 是基于 HTTP 的一种具体形式:资源位于 URL、使用标准方法,且请求不依赖之前的请求。
REST API 用什么格式响应?
REST 不规定格式:可以是 JSON、XML 或其他类型。Genesis API 以 JSON 响应,并使用 gzip 压缩。