Restful金融数据API文档怎么读？以iTick为例走一遍

Restful金融数据API文档这类东西，写的好不好直接决定了开发者接入的效率。有些厂商的文档字段说明模糊，示例代码要么缺失要么跑不通，接进去全靠猜。这篇文章以iTick的Restful API文档为例，实际走一遍从看文档到跑通请求的完整流程。

文档结构长什么样

iTick的文档站（docs.itick.org）按品类分了章节，股票、外汇、加密货币、期货、指数各自独立，每个品类下面又细分成REST API和WebSocket两块。这种组织方式挺清楚的，不用在一个大而全的页面里反复翻找，想查股票K线接口直接进对应章节就行。

请求认证方式

Restful接口的认证比较标准，走的是Token方式，注册账号后在后台就能拿到，请求的时候带上就行：

curl "https://api.itick.org/stock/quote?region=US&code=AAPL&token=你的token"

没有复杂的签名算法或者OAuth流程，对新手来说门槛不算高，看着文档抄一遍基本就能跑通第一个请求。

返回格式一致性

看了一圈接口文档，发现返回的JSON结构风格比较统一，基本都是{"code":0,"msg":"success","data":{...}}这种套路，code为0表示成功，非0的话msg里会给出具体的错误提示，调试的时候不用去猜哪里出错了，报错信息直接能看懂。

一个小细节：字段命名

字段命名上文档里也有专门的说明表，比如ld表示最新价、chp表示涨跌幅、tu表示成交额，这些缩写刚开始看可能有点懵，但文档里每个接口下面都配了字段释义表，对照着看几次就熟悉了，不至于要靠猜或者去问客服。

文档里的示例代码好不好用

这点我觉得是很多API文档容易翻车的地方——示例代码写的时候没实际跑过，读者复制过去发现根本跑步通。iTick文档里的代码示例我抽查了几个（Python、Java、Node.js的都有），基本都能直接复制运行，个别地方需要自己替换token和参数，属于正常操作，没遇到示例本身有bug的情况。

小结

一份好的Restful API文档，核心就是认证说明清楚、返回格式统一、示例代码能跑，iTick这几点基本都做到了。想实际体验的话直接去文档站逛一圈：https://docs.itick.org，注册账号在官网：https://itick.org，代码层面想看更完整的实现可以参考GitHub上的SDK仓库：https://github.com/itick-org/java-sdk。