Xproject api设计
来自Dennis的知识库
2013年1月6日 (日) 03:36Dennis zhuang(讨论 | 贡献)的版本
目录 |
变更历史
- 2012-12-13: 修改部分返回对象字段名称,添加注册接口,添加Like对象
- 2012-12-18:规范部分API接口,添加Message对象。
规范
- 协议格式:使用json序列化
- 请求:get请求遵循RESTFul风格,post请求发送json对象,字符编码UTF-8
- 应答:统一为:
{ code : 状态码 , result: 应答对象(根据API不同,结果不同) , error:错误信息(可选)}
- 应答状态码:
- 0 成功
- 1 没有授权
- 2 服务异常,需重试,一般是服务器内异常引起。
- 3 失败, 逻辑上的操作失败,比如登录失败,具体错误信息见error
- 其他待定
- 支持分页的协议都支持 start,limit参数用于分页。
- 以下API中的{user_id},都可以为self,表示登录用户自己。
- 其他协议约定: 所有created,updated等时间,返回都是yyyy-MM-dd'T'HH:mm:ss.SSS'Z'的GMT时间格式。
- 基础对象:
- User
- id long
- display_name string
- username string
- medias 音频数 int
- followers 关注者数目 int
- followings 关注中的用户数 int
- profile_picture 照片 string
- Media
- id long
- media_path 下载路径 string
- description 描述文字 string
- checksum md5 16位摘要
- user_id 拥有者 long
- likes 喜欢数目
- comments 评论数目
- created 创建时间
- Comment 评论
- id long
- content string
- user_id 评论者id long
- display_name 评论者display_name string
- created
- Like 喜欢
- id
- user_id
- media_id
- User
- Message 通知对象
- id
- from_id 事件发起者,通常为user id
- to_id 事件接收者,可以为user id,media id等
- action 事件类型,int类型,也决定了content的内容,目前包括:
- 0 评论 content则为comment id
- 1 喜欢 content则为like id
- 2 追随 content则为relation id
- 未来支持更多类型,比如送礼物之类
- content 更多关于事件的内容信息
- created 发生时间
- Message 通知对象
注册
- POST signup 请求注册,请求为
{ username : 用户名 , password 加密后的密码 , :display_name (昵称,可选) :email 邮箱(必须)}
成功即返回登录用户本身的user对象,否则告知失败信息。
登录
- POST signin 请求登录,请求为
{ username : 用户名 , password 加密后的密码 }
成功即返回登录用户本身的user对象 登录使用DES对称加密,客户端需要使用密钥对密码进行DES加密,服务端会利用同一个密钥对密码解密并判断是否匹配成功。
登出
- POST signout
用户管理
- POST users 创建一个用户,跟/signup一样
- PUT users/{user_id} 更新某用户资料,本API不遵循json格式,因为涉及到文件上传,仍然采用multipart的形式,但是返回结果仍然为json,更新内容为user对象,包括
- display_name:昵称 ,可以为空,但是和password、profile_picture必须至少有一个不为空
- password:密码,可以为空,但是和display_name,profile_picture必须至少有一个不为空
- profile_picture:图片,可以为空,但是和display_name、password必须至少一个不为空
- GET users/{user-id} 获取用户信息,返回User对象
- GET users/{user_id}/medias/liked 获取用户liked的media list,支持分页
- GET users/{user_id}/medias/commented 获取用户评论的media list,支持分页
- GET users/{user_id}/medias 获取某个用户发布的media列表,分页
- GET users/search/{username} 查询用户,接受username参数做模糊查询,返回User list。
用户关系
- GET /users/{user-id}/followings 获取该用户关注中的用户列表 user list,可分页
- GET /users/{user-id}/followed-by 获取该用户被谁关注的用户列表,可分页
- GET /users/{user-id}/relationships 同时获取关注中和被关注的用户列表,应答对象为{ followings : 关注中的对象列表 , followers : 关注该用户的对象列表 }
- POST /users/relationships 关注某些用户,请求为
{ from_id: 关注用户id to_id :被关注用户id }
- DELETE /users/relationships 取消关注某些用户,请求为
{ from_id: 关注用户id to_id :被关注用户id }
Media管理
- GET medias/{id} 获取某个media_id的media对象
- GET medias/search/{keywords} 查询media,根据description和owner来查询
- GET medias/popular 获取最热media列表,可设置timestamp,可分页
- POST users/{user_id}/medias 上传media,owner为当前session的user,请注意,本API不遵循json格式,因为涉及到文件上传,仍然采用multipart的形式,但是返回结果仍然为json,上传内容为:
- description : 描述文字(可选)
- user_id : 上传者的user_id(服务端会检查是否为当前用户),
- media_file: media文件
- checksum : 32位md5校验码
- DELETE /medias/{id} 删除某个media,服务端会检查该media是否为当前session的user所有。
- GET /users/{user-id}/medias/recent 获取用户关注的用户最近的media list,可以不断下拉,接收start,limit,timestamp和order参数。
- start 开始offset
- limit 限制返回多少条
- timestamp 刷新时间线
- order 排序依据,默认按照发布时间排序,可设置的值包括
- created 按照发布时间排序,默认
- smart 智能排序,按照media的关注度、该发布者的关注度、被喜欢次数、被评论次数等因素综合评分排序
- user_defined 用户自定义排序(还需要讨论)
- 返回结果为:
{ code: 代码 , result: { timeline: 时间线 :medias media对象列表}}
评论
- GET /medias/{media-id}/comments 获取某个media的评论列表
- POST /medias/{media-id}/comments 为某个media评论,评论者为当前session的user,post内容为comment对象
- DELETE /comments/{comment-id} 删除某个media的评论,评论者为当前session的user
喜欢
- GET /medias/{media-id}/likes 获取某个media的喜欢的用户列表 user list
- POST /medias/{media-id}/likes 提交喜欢动作,喜欢某个media
- DELETE /likes/{like_id} 取消喜欢某个media
消息
- GET /users/{user_id}/messages 获取某用户的消息列表,分页
- GET /users/{user_id}/messages/recent 获取某用户订阅的最近消息列表,按照时间排序,分页
统计
- POST /stats/{event} 事件统计,
- event包括:
- play 播放
- 提交的内容包括:
- user_id:用户id,不可以为空
- media_id: media的id,必需
- event包括: