XXX电子商务平台API文档
======
基础说明
背景
[说明文档用途。]
编写本文的目的是为了将系统功能进行模块化、服务化,将用户的操作以服务的方式提供。系统与系统之间遵循服务规范,将系统与系统之间的交互转为定制化服务交互,以实现系统与系统之间的集成。
基本约束
基本设计原则
参考《86-RestAPI设计指南》
字符集
- 所有接口字符集采用UTF-8。
返回类型约束
- 所有接口返回必须是严格定义的JSON类型。
接口版本约束
- 不允许发布无版本号的接口。
- 接口版本首先解决的是一组接口的版本问题。
请求公共约束
请求的基本模板:1
2
3
4
5
6curl -X[HTTP METHOD] -H "Content-Type: application/json" -H "[token-info]:"
"https://api-dev.[groupname].xiaoyuyu.io/[client-group]/[service-group-name]/
[version]/[endpoint]" -d '{
"head": [meta-parameters],
"body": [content]
}'
URL整体规划
域名规范
域名规划
- 开发环境: https://api-dev.payment.xiaoyuyu.io/
- 测试环境: https://api-test.payment.xiaoyuyu.io/
- 预演环境: https://api-staging.payment.xiaoyuyu.io/
- 线上测试环境: https://api-onlinetest.payment.xiaoyuyu.io/
- 生产环境: https://api.payment.xiaoyuyu.io/
- 其中,线上测试环境是上线过程中备用,比如线上一共3台生产环境服务器,把其中一台从生产环境切掉,更新程序并且将域名指向它,测试完之后再将生产环境流量切换过来。
接口认证
基本数据类型约定
此约定是系统整体容错的一部分,但是无论接口使用者还是接口生产者,都不应该因为此容错而减少自己模块本来需要的容错工作。
数据类型 | 类型说明 | 默认值 | 备注 |
---|---|---|---|
JSONObject | JSON对象 | {} | |
JSONArray | JSON数组 | [] | 数组中不允许使用混合类型 |
Integer | 整型 | Integer.MIN_VALUE | |
Float | 浮点型 | Float.MIN_VALUE | |
Char | 字符型 | 空格 | |
String | 字符串 | 空字符串 | 不允许直接返回NULL |
Boolean | 布尔型 | Boolean.FLASE | 默认返回false |
嵌套对象 | 嵌套对象 | {} | 根对象返回空,子对象不处理 |
嵌套数组 | 嵌套数组 | [] | 根对象返回空,子对象不处理 |
公共输入参数规范
TODO: 补充token,加密,国际化,等等
字段名 | 必须 | 数据类型 | 描述 | 示例 |
---|---|---|---|---|
requestInfo | 是 | JSONObject | 表达每个请求的信息 | |
requestInfo.sessionId | 是 | String | UUID,每次进入APP到退出算一次会话 | |
requestInfo.reqId | 是 | String | UUID,每次请求独立生成一个Id | |
apkInfo | 是 | JSONObject | 表达每个apk的信息 | |
apkInfo.apkType | 是 | String | 表示APK本身的类型 | Dev,Debug,beta |
apkInfo.apkId | 是 | String | UUID,每次安装会单独生成一个apkId | |
apkInfo.apkVersion | 是 | String | App的内部版本号 | |
apkInfo.appVersion | 是 | String | App的显示版本号 | |
clientInfo | 是 | JSONObject | 表达客户端的信息 | |
clientInfo.ip | 是 | String | 客户端ipV4的地址 | |
clientInfo.romInfo | 是 | String | 定制版操作系统的信息 | |
clientInfo.deviceTag | 否 | String | 设备的标记 | |
clientInfo.osInfo | 否 | String | 操作系统的信息 | |
userInfo | 是 | JSONObject | 表达用户的信息 | |
userInfo.userId | 是 | String | 用户的唯一标识符 |
公共返回对象约定
1 | { |
公共错误编码及说明
code | 描述 | 适用范围 | 备注 |
---|---|---|---|
20000 | 请求成功 | 全部 | 200表示成功,后两位00是补充编码 |
公共数据字典
字段名 | 取值 | 适用范围 | 备注 |
---|---|---|---|
status | 1,2,3 | 全部文档 | 无 |
订单服务
查询订单列表
接口规范
URL | /{baseUri}/orders | ||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
访问权限 | 基本验证,Https,用户验证 | ||||
说明 | 查询某个用户的订单列表 | ||||
请求参数 | |||||
参数名称 | 必须 | 数据类型 | 描述 | 示范 | |
body.pageSize | YES | Integer | 一页的查询条目数 | 默认是10,最大值50 | |
body.pageNo | YES | Integer | 查询的页数 | 默认是1 | |
body.sortBy | NO | String | 参见数据字典,排序规则 | 默认按照时间倒排 | |
body.from | NO | String | 转换为Date,查询范围的开始时间 | 示范:2019-01-01 22:00:00 | |
body.to | NO | String | 转换为Date,查询范围的结束时间 | 示范:2019-01-01 22:00:00 | |
返回参数 | |||||
responseData.pageCount | YES | Integer | 一共有多少页 | ||
responseData.pageNo | YES | Integer | 当前的页数 | ||
responseData.data | NO | JSONObject | 订单详细信息 |
输入参数示范
1 | curl -XGET -H "Content-Type: application/json" -H "Access-Token:abcd1234" "https://api-dev.haitao.xiaoyuyu.io/mobile/data-platform/v1/orders/base-orders" -d '{ |
返回参数示范
版权声明
本文标题:87-一个建议的接口文档模板
文章作者:盛领
发布时间:2019年01月14日 - 22:16:34
原始链接:http://blog.xiaoyuyu.net/post/abe8667.html
许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。
如您有任何商业合作或者授权方面的协商,请给我留言:sunsetxiao@126.com

欢迎您扫一扫上面的微信公众号,订阅我的博客!
坚持原创技术分享,您的支持将鼓励我继续创作!