Xproject api设计

来自Dennis的知识库
2012年12月18日 (二) 03:22Dennis 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参数用于分页。
  • 以下${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
      • path 下载路径 string
      • description 描述文字 string
      • checksum 校验和 int
      • 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
    • Message 通知对象
      • id
      • from_id 事件发起着
      • to_id 事件接收者
      • action 事件类型,int类型,目前包括:
        • 0 评论
        • 1 喜欢
        • 2 追随
        • 未来支持更多类型,比如送礼物之类
      • content 更多关于事件的内容信息

注册

  • POST signup 请求注册,请求为
   { username : 用户名 , password 加密后的密码 , :display_name (昵称,可选) :email 邮箱(必须)}

成功即返回登录用户本身的user对象,否则告知失败信息。

登录

  • POST signin 请求登录,请求为
   { username : 用户名 , password 加密后的密码 }

成功即返回登录用户本身的user对象 登录使用DES对称加密,客户端需要使用密钥对密码进行DES加密,服务端会利用同一个密钥对密码解密并判断是否匹配成功。

用户管理

  • POST users 创建一个用户,跟/signup一样
  • GET users/{user-id} 获取用户信息,返回User对象
  • GET users/{user_id}/medias/liked 获取用户liked的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 }

Media管理

  • GET /medias/{id} 获取某个media_id的media对象
  • GET /medias/search 查询media,根据description和owner来查询
  • GET /medias/popular 获取最热media列表,可设置limit
  • POST /medias 上传media,owner为当前session的user,上传内容为:
   { description : 描述文字(可选), user_id : 上传者的user_id(服务端会检查是否为当前用户),  media_bytes: base64编码的bianry数据 }
  • DELETE /medias/{id} 删除某个media,服务端会检查该media是否为当前session的user所有。
  • GET /users/{user-id}/medias/recent 获取用户关注的用户最近的media list,可以不断下拉,接收start,limit和order参数。
    • start 开始offset
    • limit 限制返回多少条
    • order 排序依据,默认按照发布时间排序,可设置的值包括
      • created 按照发布时间排序,默认
      • smart 智能排序,按照media的关注度、该发布者的关注度、被喜欢次数、被评论次数等因素综合评分排序
      • user_defined 用户自定义排序(还需要讨论)

评论

  • GET /medias/{media-id}/comments 获取某个media的评论列表
  • POST /medias/{media-id}/comments 为某个media评论,评论者为当前session的user,post内容为comment对象
  • DELETE /medias/{media-id}/comments/{comment-id} 删除某个media的评论,评论者为当前session的user

喜欢

  • GET /medias/{media-id}/likes 获取某个media的喜欢的用户列表 user list
  • POST /medias/{media-id}/likes 喜欢某个media
  • DELETE /medias/{media-id}/likes 取消喜欢某个media

消息

  • GET /users/${user_id}/messages 获取某用户的消息列表,分页
  • GET /users/self/messages/recent 获取自己订阅用户的最近消息列表,按照时间排序,分页
个人工具
名字空间

变换
操作
导航
工具箱