API接口设计项目说明指导书.docx

XXAPI
接口设计说明书

企业
11月25日

文档管理信息表
专题
XX api接口设计说明书
版本
V0.1
内容

关键字

参考文档

创建时间

创建人

最新公布日期

文档变更统计表
修改人
修改时间
修改内容

创建

目 录
文档变更统计表 3
目 录 1
引言 1
编写目标 1
背景 1
定义 1
参考资料 1
综述 2
统一输入输出参数 2
必需登录才能访问接口 2
错误返回码列表 3
用户接口 4
用户注册（user/signup） 4
用户登录（user/signin） 5
优惠券接口 9
我优惠券（coupon/mycoupon） 9

引言
编写目标
{说明编写这份用户手册目标，指出预期读者。}
背景
{说明：
a． 这份用户手册所描述软件系统名称；
b． 该软件项目标任务提出者、开发者、用户（或首批用户）及安装此软件计算站中心。}
定义
{列出本文件中用到专门术语定义和外文首字母组词原词组。}
参考资料
{列出有用参考资料，如：
a． 本项目标经核准计划任务书或协议、上级机关批文；
b． 属于本项目标其它已发表文件；
c． 本文件中各处引用文件、资料、包含所要用到软件开发标准。
列出这些文件资料标题、文件编号、发表日期和出版单位，说明能够得到这些文件资料起源。}

综述
统一输入输出参数
Request
参数名
类型
是否必需
描述
language
String
Y
cn:汉字，en:英文，th：泰文
uid
Int
Y
用户ID.
sid
String
Y
SessonId（TOKEN）
（不需要登录就能调用接口、注册接口、登录接口，uid和sid两个参数不需要输入）

Response
参数名
类型
是否必需
描述
succeed
Int
Y
0：失败，1：成功
error_code
Int
N
错误码
error_desc
String
N
错误消息

必需登录才能访问接口
接口名称
描述
user/signout
用户退出
user/photoupload
照片上传
user/changeprofile
修改用户资料
user/changepassword
修改用户密码
user/info
获取用户信息

错误返回码列表
error_code
error_desc
1
授权过期
500
服务器内部错误
600
账号被锁定
10001
手机号码不能为空
10002
密码不能为空
10003
验证码不能为空
10004
平台类型不正确
10005
手机验证码不正确
10006
手机验证码已失效
10007
用户类型不正确
10008
用户名不能为空
10009
原密码不能为空
10010
新密码不能为空
10011
原密码不正确
10012
经度不能为空
10013
纬度不能为空
10014
对象用户ID不能为空

用户接口
用户注册（user/signup）
接口
user/signup
描述
用户注册
验证
Session
方法
GET/POST

Request
参数名
类型
是否必需
描述
mobile
Int
Y
注册手机号.
verify_code
String
Y
手机验证码
password
String
Y
密码
platform
String
Y
平台类型（ios,android）

Response
参数名
类型
是否必需
描述
sid
String
Y
SessonId（TOKEN）
uid
Int
Y
用户ID

Example
Request
{
"mobile": "",
"verify_code": "123456",
"password": "111111",
"platform": "android"
}

Response
1.错误情况
{
"succeed": 0,
"error_code": 10006,
"error_desc": "手机验证码已失效"
}

2.正常情况
{
"sid": "sess_573d27b370dc7",
"uid": "28",
"succeed": 1
}

用户登录（user/signin）
接口
user/signin
描述
用户登录
验证
Session
方法
GET/POST

Request
参数名
类型
是否必需
描述
mobile
Int
N
注册手机号. (type=1时必需)
username
String
N
用户名(type=2、3、4时必需)
password
String
N
密码(type=1时必需)
type
Int
Y
用户类型
1：手机号
2：QQ
3：微信
4：微博
platform
String
Y
平台类型（ios,android）

Response
参数名
类型
是否必需
描述
sid
String
Y
SessonId（TOKEN）
user
Array
Y
用户信息
id
Int
Y
用户ID
user_group
Int
Y
用户角色
1：一般用户
2：专车车主
nickname
String
Y
昵称
email
String
Y
邮箱
mobile
String
Y
手机号
name
String
Y
姓名
username
String
Y
用户名
gender
Int
Y
性别
0：男
1：女
age
Int
Y
年纪
birthday
String
Y
出生日期
avatar
String
Y
头像URL
joined_at
String
Y
注册时间

Example
Request
{
"type": "1",
"mobile": "",
"password": "111111",
"platform": "android"
}

Response
1.错误情况
{
"succeed": 0,
"error_code": ,
"error_desc": "密码错误"
}

2.正常情况
{
"sid": "sess_573d285820a42",
"user": {
"id": 3,
"user_group": 1,
"nickname": "test001",
"email": "",
"mobile": "",
"name": "王小二",
"username" : "",
"gender": 0,
"age": 26,
"birthday ":"1985-10-10",
"avatar": "/travel/public/uploadFile/avatar/empty.png",
"joined_at": "-05-03 10:15:53"
},
"succeed": 1
}

优惠券接口
我优惠券（coupon/mycoupon）
接口
coupon / mycoupon
描述
我优惠券
验证
Session
方法
GET/POST