|
API是两个系统之间交互的协议，在设计时需充分考虑清楚服务请求方和服务提供方的场景。
对外API是系统对API用户提供的服务，需要考虑到API用户的使用特点。本文提出了针对API用户的设计标准，作为参考。
设计要点
API设计时需要考虑以下方面：灵活性、一致性、兼容性
- 灵活性，API用户使用程序调用接口，因此一个接口应该尽可能满足多种场景，减少限制；
- 一致性，API用户学习接口有成本，因此不同的接口之间的术语和逻辑尽可能保持一致；
- 兼容性，API用户的程序修改起来有成本，因此每次接口的更新需要保持向前兼容（即兼容旧版本）。
Rest接口设计
设计输出
Rest接口设计输出需包含以下完整内容
- 描述
- 方法：如 GET, POST
- 路径：如 /market/kline
- 请求参数：请求参数需要包括如下字段：
- 限频：如 10次/2秒
- 返回数据：返回数据需要包括如下字段
- 返回错误码：返回错误码需要包括如下字段：
示例
获取商品信息
此接口返回指定的商品信息。
限频：10秒/2次
请求路径：GET /market/depth
请求参数
| 名称 | 类型 | 是否必需 | 默认值 | 说明 |
|---|
| symbol | string | 是 | 无 | 交易对 | | depth | int | 否 | 20 | 返回的深度梳理 | | size | string | 是 | step0 | 深度价格的聚和度: [step0, step1, step2, step3, step4, step5] |
返回数据
| 名称 | 类型 | 描述 |
|---|
| ts | long | 调整为新加坡时间的时间戳，单位毫秒 | | bids | object | 当前的所有买单 [price, size] | | asks | object | 当前的所有卖单 [price, size] |
返回错误码
| 错误码 | 错误消息 | 说明 |
|---|
| invalid-parameter | invalid symbol | 无效的交易对 | | invalid-parameter | invalid period | 请求K线，period参数错误 | | invalid-parameter | invalid depth | 深度depth参数错误 | | invalid-parameter | invalid type | 深度type 参数错误 | | invalid-parameter | invalid size | size参数错误 | | invalid-parameter | invalid size,valid range: [1, 2000] | size参数错误 | | invalid-parameter | request timeout | 请求超时 |
| 
转播
