[关闭]
@khan-lau 2017-04-02T10:58:45.000000Z 字数 5029 阅读 1554

BallPython接口协议

未分类

版本号: v0.9.0

1 协议约定

1.1 如果请求正确, 应返回数据类型

  1. --response
  2. result:{
  3. "code":200
  4. "message": "S_OK",
  5. "data": {
  6. "array":[] //此处,根据需求返回不同类型数据.
  7. }
  8. }

1.2 如果请求失败, 应返回数据类型

  1. --response
  2. {
  3. "code":500,
  4. "message": "FA_UNAUTHORIZED" //见1.5 错误代码定义
  5. }

1.3 request

https://host:port/interface
其他协议字段使用 form 提交
通过https 协议保证安全性.
建议使用 Go Daddy Secure Certificate Authority - G2证书
禁止缓存的页面, 请求需携带If-Modified-Since:"GMT时间戳"
连接使用 tls 1.0+ 进行加密, 避开 ssl 的漏洞
token 有时效限制, 过期后返回对应err_code.(参考协议1.5)
login成功, header 中返回 cookie, 后续请求都需携带对应 cookie

1.4 编码集

协议中约定所有请求必须使用 utf8编码. 涉及 url-encode, 也需使用 utf8.
涉及分页的接口 暂定每页20条记录.

1.5 错误代码

Message字段

S_OK                          - 表示操作成功,同时返回对应的Session ID和用于cookie校验的值
FA_UNAUTHORIZED               - 表示用户名或者密码不匹配,或者用户不存在
FA_EXPIRED                    - 用户账户过期
FA_INVALID_VERIFY_CODE        - 校验码不正确 (备用)
FA_INVALID_VERIFY_COOKIE      - cookie不正确
FA_INVALID_TOKEN              - TOKEN不合法,通常是校验码已过期
FA_NEED_VERIFY_CODE           - 需要校验码 (备用)
FA_USER_LOCKED                - 用户处于锁定状态 (备用)
FA_USER_SUSPENDED             - 用户被禁用 (备用)
FA_USER_WRONG_STATUS          - 用户状态错误 (备用)
FA_DB_ERROR                   - 数据库异常
FA_PARAM_ERROR                - 参数异常
FA_DATA_NOT_FOUND             - 未找到结果
FA_USER_EXISTS                - 用户名或手机号重复
FA_ORDER_EXISTS               - 用户重复报名
FA_SIGN_ERROR                 - 签名错误

2 基础数据类型

2.1 User

  1. "user":{
  2. "id":33ul, --id
  3. "user":"john117", --登录用户名
  4. "passwd":"qwer1234", --登录密码
  5. "true_name":"张三", --姓名
  6. "phone":"13801030311", --电话号码
  7. "reg_time":1424312000L, --注册日期 unix时间戳
  8. "expired_time":1424312213L, --失效日期 unix时间戳
  9. "charge": 132, --账户余额 分为单位
  10. "own":"123", //介绍人id
  11. .... --其他字段, 可自行扩展.
  12. }

2.2 比赛

  1. Race: {
  2. 'id' : 123, --比赛id
  3. 'type' : "NBA", --比赛类型
  4. 'event' : "2016-08-11 18:00:00", --比赛时间
  5. 'team_left' : "小牛队", --主队
  6. 'team_right' : "网队" --客队
  7. }

2.3 推送条件

  1. Condition:{
  2. 'id':123,
  3. 'uid':123, -- 条件所属用户id
  4. 'rid':123, -- 比赛id
  5. 'left_team': '小牛队', -- 主队
  6. 'right_team' : '网队', -- 客队
  7. 'event': 1488102400000L, -- 比赛开始时间, 1970至今的毫秒数
  8. 'cond':1, -- 条件, 1:让分, 2:总分
  9. 'expr':-1, -- 表达式, -1:小于等于, 0:等于, 1大于等于
  10. 'val':132, -- 条件阀值
  11. 'status':-1, -- 发送状态, -1:未发送或出错, 0:发送中, 1:发送完成
  12. 'type':1, -- 推送类型, bit0 push, bit1sms
  13. 'timestamp': 1488102400000L, -- 记录录入时间, 1970至今的毫秒数
  14. 'finish_time' :1488102400000L --最后一次触发推送时间
  15. }

2.4 评论

  1. msg:{
  2. 'id':123,
  3. 'parent':0, -- 普通评论为0, 回复则为回复消息的id
  4. 'race_id':123, -- 比赛id
  5. 'from': 'user1', -- (作者)发件人user
  6. 'to': null, -- 被回复人的user, 如普通评论, 则为空
  7. 'reply': null, -- 回复的原始消息内容, 如普通评论, 则为空
  8. 'msg' : 'adfsa', -- 评论消息内容
  9. 'timestamp': 1488102400000L -- 评论发布时间, 1970至今的毫秒数
  10. }

3 接口说明

3.1 鉴权接口 login

鉴权接口.

URL:
https://host:port/login

参数

Name Description
user 用户id
passwd
dtoken Optional 设备串码, [ios|adr]@udid

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. "data": {
  5. "token" : <string> ,
  6. "user": User --见协议2.1
  7. }
  8. }

请求失败

  1. {
  2. "code":500
  3. "message": "FA_UNAUTHORIZED" //见1.5 错误代码定义
  4. }

3.1.1 基本流程

init接口会提供在header中提供名为fast4ward.sid的cookie, 后续接口调用请求需携带该cookie.

Created with Raphaël 2.1.2ServerServerBrowserBrowserInit auth_cookiesaved auth_cookielogin with http cookie headerretrun tokenrest_passwd with http cookie header and tokenget_news with http cookie header

3.2 修改密码

修改密码
URL:
https://host:port/reset_passwd

参数

Name Description
user user
token token
passwd 旧密码
new_passwd 新密码

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. "data": {}
  5. }

3.3 获取比赛列表

获取比赛列表
URL:
https://host:port/list

参数

Name Description
user user
token token

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. "data": {
  5. "array":[
  6. Race, --Race定义见协议 2.2
  7. Race,
  8. ......
  9. ]
  10. }
  11. }

3.4 获取比赛成绩汇总

获取比赛成绩汇总
URL:
https://host:port/score

参数

Name Description
user user
token token
id 比赛id

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. "data": {
  5. "asia_array":[
  6. {
  7. "score":132, --比分
  8. "time": "2016-08-11 18:00:00" --时间
  9. }
  10. ......
  11. ],
  12. "over_array":[
  13. {
  14. "score":132,
  15. "time": "2016-08-11 18:00:00"
  16. }
  17. ]
  18. }
  19. }

3.5 设定推送通知条件

定制推送通知条件
URL:
https://host:port/set_push_rule

参数

Name Description
user user
token token
uid user对应的用户id
rid 比赛id
left_team 主队
right_team 客队
event 比赛开始时间, 1970至今的毫秒数
cond 条件, 1:让分, 2:总分
expr 表达式, -1:小于等于, 0:等于, 1大于等于
val

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. "data": {
  5. "condition": Condition --见协议2.3
  6. }
  7. }

3.6 获取推送条件列表

分页获取推送条件列表

URL:
https://host:port/get_push_rule

参数

Name Description
user user
token token
offset Optional 分页偏移量, 与limit组合使用, 默认为0
limit 当页记录数
order Optional 按录入时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. "data": {
  5. "offset" : 0, //分页偏移量, 透传
  6. "total" : 5, //共5条记录.
  7. "array":[
  8. condition, --condition定义见协议 2.3
  9. condition,
  10. ......
  11. ]
  12. }
  13. }

3.7 获取用于评论的比赛列表

分页获取用于评论的比赛列表

URL:
https://host:port/get_race

参数

Name Description
user user
token token
all Optional 获取或获取全部比赛, 无此参数则获取未过期的比赛
search Optional 球队名称模糊搜索
offset Optional 分页偏移量, 与limit组合使用, 默认为0
limit 当页记录数, -1表示获取所有记录
order Optional 按录入时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. "data": {
  5. "offset" : 0, //分页偏移量, 透传
  6. "total" : 5, //共5条记录.
  7. "array":[
  8. race, --race定义见协议 2.2, 此处获取的race.eventunix timestamp格式, 长整形
  9. race,
  10. ......
  11. ]
  12. }
  13. }

3.8 获取对应比赛的评论

分页获取对应比赛的评论列表

URL:
https://host:port/get_msg_by_race

参数

Name Description
user user
token token
race_id 比赛id
search Optional 指定获取某个用户的评论
offset Optional 分页偏移量, 与limit组合使用, 默认为0
limit 当页记录数, -1表示获取所有记录
order Optional 按录入时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. "data": {
  5. "offset" : 0, //分页偏移量, 透传
  6. "total" : 5, //共5条记录.
  7. "array":[
  8. msg, --race定义见协议 2.4
  9. msg,
  10. ......
  11. ]
  12. }
  13. }

3.9 发表评论

发布评论或回复评论

URL:
https://host:port/post_msg_by_race

参数

Name Description
user user
token token
race_id 赛事id
parent Optional 被回复的评论所对应的id
to Optional 被回复的评论所对应作者user, parent不为0时, 必填
reply Optional 被回复的评论原始内容, parent不为0时, 必填
msg 评论的内容

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. "data": {
  5. "msg": msg --见协议2.4
  6. }
  7. }

3.10 删除评论

删除用户发布的指定评论

URL:
https://host:port/del_msg

参数

Name Description
user user
token token
id 评论id

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. }

3.11 屏蔽非法评论

屏蔽用户发布的指定评论

URL:
https://host:port/admin_filter_msg

参数

Name Description
user user, 需特权用户
token token
id 评论id

response
请求成功:

  1. {
  2. "code": 200,
  3. "message": "S_OK",
  4. }
添加新批注
在作者公开此批注前,只有你和作者可见。
回复批注