XXX电子商务平台API文档

======

基础说明

背景

[说明文档用途。]
编写本文的目的是为了将系统功能进行模块化、服务化，将用户的操作以服务的方式提供。系统与系统之间遵循服务规范，将系统与系统之间的交互转为定制化服务交互，以实现系统与系统之间的集成。

基本约束

基本设计原则

参考《86-RestAPI设计指南》

字符集

所有接口字符集采用UTF-8。

返回类型约束

所有接口返回必须是严格定义的JSON类型。

接口版本约束

不允许发布无版本号的接口。
接口版本首先解决的是一组接口的版本问题。

请求公共约束

请求的基本模板:

curl -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-[env-name].[groupname].domain.io/[clientGroup]/[version]/[endpoint]

域名规划

开发环境: 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	用户的唯一标识符

公共返回对象约定

{
  "responseCode": [responseCode],
  "responseInfo": {
    "userMessage": [userMessage],
    "internalMessage": [internalMessage],
    "guideline": [guideline link]
  },
  "link": 
    {
	 "document":" https://[domain]/docs#zoos",
	 "href":[uri-info],
	 "title":[doc-title],
	 "type":"application/[vnd.yourformat]+json"
  },
  "responseData":[responseData]
}

公共错误编码及说明

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	订单详细信息

输入参数示范

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 '{
  "head": [meta-parameters],
  "body": {
    "pageSize":10,
    "pageNo":1
  }
}'

返回参数示范

本文标题:87-一个建议的接口文档模板

文章作者:盛领

发布时间:2019年01月14日 - 22:16:34

原始链接:http://blog.xiaoyuyu.net/post/abe8667.html

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际转载请保留原文链接及作者。

如您有任何商业合作或者授权方面的协商，请给我留言：sunsetxiao@126.com

欢迎您扫一扫上面的微信公众号，订阅我的博客！

坚持原创技术分享，您的支持将鼓励我继续创作！