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

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, bit1为sms
  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.event为unix 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. }
添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注