支付 API 设计

最近在做外汇产品的 API Review 工作。国外的 API 基本都是 Restful 的，包括 Payal、Wise、Adyen，现在都基本提供了 Restful 的 API 了，但是国内目前看微信、支付宝等都还没有往 Restful 上走。

其实不管是不是 Restful，其实只是在 API 设计上的「术」的区别，Restful 从模型的角度出发，传统的 RPC 模式从交互的角度出发。如果 API 设计合理的话，基本都是动词+名词的组合，区别并不是很大。从「道」的层面，其实还是抽象的维度问题。

从本次模型的 Review 结果看，从抽象的原则上思考，设计上普遍存在几个共性的问题：

1. API 过碎：咨询保证金、咨询下单限额、咨询可交割日期被拆分成了多个服务。理论上，这三者都是在下单之前的咨询，在调用时间点上是一致的，应该合并。

2. 字段含义不清：API 和 API 之间字段命名不统一。部分请求和响应中有非业务字段，如身份标识、版本号等。

3. API 命名过于随意：这个是 RPC 相对于 Restful 的一个劣势。Restful 只需要确定模型，对于每一类模型就是 GET/PUT/POST/DELETE。

经过 Review 后，我们对 API 做了如下的原则限定：

• 固定动作：对于所有的下单、交割交易，只定义咨询、查询、下单、修改、撤销五个动词。未来如果要过渡到 Restful，这里面可以找到简单的映射：

• 咨询：就是预创建，Restful 中对应的是 HEAD。

• 下单：PUT。

• 修改：POST。

• 撤销：CANCEL。

• 查询：GET。

• 明确数据字典。定义所有有业务含义的 terms 以及类型、长度。杜绝身份标识、版本号此类无业务含义字段出现在对外的 API 中。

• 明确 API 命名规范：动词+名词。