“Xproject api设计”的版本间的差异

2012年12月8日 (六) 16:30的版本

规范

• 协议格式：使用json序列化
• 请求：get请求遵循RESTFul风格，post请求发送json对象，字符编码UTF-8
• 应答：统一为：

   { code : 状态码 , result: 应答对象（根据API不同，结果不同） ,  error:错误信息(可选)}

• 应答状态码:
  • 0 成功
  • 1 没有授权
  • 2 服务异常，需重试，一般是服务器内异常引起。
  • 3 失败， 逻辑上的操作失败，比如登录失败，具体错误信息见error
  • 其他待定
• 其他协议约定： 所有created,updated等时间，返回都是yyyy-MM-dd'T'HH:mm:ss.SSS'Z'的GMT时间格式。
• 基础对象:
  • User
    • user_id long
    • display_name string
    • username string
    • medias 音频数 int
    • followers 关注者数目 int
    • followings 关注中的用户数 int
    • profile_picture 照片 string
  • Media
    • media_id long
    • path 下载路径 string
    • description 描述文字 string
    • checksum 校验和 int
    • user_id 拥有者 long
    • created 创建时间
  • Comment 评论
    • comment_id long
    • content string
    • user_id 评论者id long
    • display_name 评论者display_name string
    • created

用户管理

• GET /users/{user-id} 获取用户信息，返回User对象
• GET /users/{user-id}/media/recent 获取用户关注的用户最近的media list，可以不断下拉，接收start,limit和order参数。
  • start 开始offset
  • limit 限制返回多少条
  • order 排序依据，默认按照发布时间排序，可设置的值包括
    • created 按照发布时间排序，默认
    • smart 智能排序，按照media的关注度、该发布者的关注度、被喜欢次数、被评论次数等因素综合评分排序
    • user_defined 用户自定义排序（还需要讨论）
• GET /users/self/media/liked 获取自己liked的media list
• GET /users/self/medias 获取自己发布的media列表，同样分页
• GET /users/search 查询用户，接受username参数做模糊查询，返回User list。

用户关系

• GET /users/{user-id}/followings 获取该用户关注中的用户列表 user list，可分页
• GET /users/{user-id}/followed-by 获取该用户被谁关注的用户列表，可分页
• GET /users/{user-id}/relationship 同时获取关注中和被关注的用户列表，应答对象为{ followings : 关注中的对象列表 , followers : 关注该用户的对象列表 }
• POST /users/{user-id}/relationship 关注某些用户，请求为

   { follow : target_user_id_list }

Media管理

• GET /medias/{id} 获取某个media_id的media对象
• GET /medias/search 查询media，根据description和owner来查询
• GET /medias/popular 获取最热media列表，可设置limit
• POST /medias 上传media，owner为当前session的user，上传采用http post，类似上传文件。返回结果为media对象。
• DELETE /media/{id} 删除某个media，服务端会检查该media是否为当前session的user所有。

评论

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

喜欢

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