作者:glzjin

最后更新时间:2018年5月13日

一、写作目的

解释说明星空辽阔账号系统的设计以及相关 API.

二、基本设计

1.对外接口(API)部分

用户模块

  • 用户注册接口–直接注册
  • 用户登录(ID/ 邮箱)
  • 用户资料编辑模块

激活管理模块

  • 激活码使用
  • 子系统权限校验模块

论坛模块

  • 板块拉取( 以 app id 为依据)
  • 发帖
  • 评论

2.约定

  • 用户 角色数字
    • 1=超级管理员
    • 2=保留
    • 3=保留
    • 4=用户
  • 请求格式
    • 如无特殊说明,请求体与返回体均为 json!
  • App 要接入的话,有以下几个参数要 Hold.
    • AppId:在系统内 APP  的 ID,永久不变
    • OAuth ClientID & ClientSecret:OAuth  登录的 APP 信息对。
    • SignKey:签名验证 Key,千万要保存到安全的地方!

三、接口具体说明

  • 0、服务器状态获取
    • 接口名称:服务器ping测试
    • 接口用途:用于确认服务器状态。
    • 接口地址:https://accounts.extstars.com/api/v2/ping
    • 请求方法:GET
    • 接口参数:
    • 接口返回格式:
      • 1.code={code}
        • code=100 服务器正常运行
        • code=101 服务器维护中
  • 1、用户账户事务相关接口。
    • 注册新用户。
      • 接口名称:用户注册。
      • 接口用途:用于新用户的注册。
      • 接口地址:https://accounts.extstars.com/api/v2/reg
      • 请求方法:POST
      • 接口参数格式:
        1. email={email}
        2. password={password}
        3. user_name={nickname}
      • 接口返回格式:
        1. code={code}
          • code=100 注册成功
          • code=101 重复的email
          • code=102 资料不全 或长度不够
  • 2、日常登陆接口。
    • 用户名密码登陆。
      • 接口名称:用户登录。
      • 接口用途:用于新用户的登录。
      • 接口地址:https://accounts.extstars.com/oauth/token
      • 请求方法:POST
      • 接口参数格式:
        1. grant_type=password
        2. client_id={id}
        3. client_secret= {secret}
        4. username={email}
        5. password={password}
        6. scope=*
      •  接口返回格式:
        • 分为两种情况,登录成功和失败时。
        • 1.登录成功(HTTP状态码 200):
          • token_type=Bearer
          • expires_in=31536000
          • access_token={请求令牌,在接下来的请求中会主要用到。}
          • refresh_token={刷新令牌,此处基本用不到}
        • 2.登录失败(HTTP状态码 401):
          • error=错误原因
          • message=错误消息
    • 令牌刷新
      • 接口名称:令牌刷新。
      • 接口用途:用于用户的令牌刷新。
      • 接口地址:https://accounts.extstars.com/oauth/token
      • 请求方法:POST
      • 接口参数格式:
        1. grant_type=refresh_token
        2. client_id={id}
        3. client_secret= {secret}
        4. refresh_token={refresh_token}
        5. scope=”
      •  接口返回格式:
        • 分为两种情况,刷新成功和失败时。
        • 1.刷新成功(HTTP状态码 200):
          • token_type=Bearer
          • expires_in=31536000
          • access_token={请求令牌,在接下来的请求中会主要用到。}
          • refresh_token={刷新令牌,此处基本用不到}
        • 2.刷新失败(HTTP状态码 401):
          • error=错误原因
          • message=错误消息

 

  • 同时请注意,以下接口需要在 HTTP 头中带上  Authorization 头 来作为验证。
  • 例如:
  • GET https://accounts.extstars.com/api/v2/auth/ping
    Authorization: Bearer {访问令牌}

    如果验证失败则会被跳转到登录页面(accept 里没 json, 有 json则返回403码,可以参考 OAuth  在 RFC 里定义的错误码进行判断),可以以此作为标志。

 

  •  3、登录状态确认接口
    • 接口名称:登录状态确认。
    • 接口用途:用户是否在正确登录状态。
    • 接口地址:https://accounts.extstars.com/api/v2/auth/ping
    • 请求方法:GET
    • 接口参数格式:无参数
    • 接口返回参数:
      • code=100 已登录
        • uid={id}
        • user_name={user_name}
        • app_id={current_app_id}
        • user_avatar={avatar_url}
        • user_score={score}
  • 4、更改密码接口
    • 接口名称:更改密码。
    • 接口用途:用于修改密码。
    • 接口地址:https://accounts.extstars.com/api/v2/auth/change_password
    • 请求方法:POST
    • 接口参数格式:
      • password={new_password}
    • 接口返回参数:
      • code=100 操作成功
    • 备注:此接口调用后需要用新信息来重新登录!
  • 5、更改昵称接口
    • 接口名称:更改昵称。
    • 接口用途:用于修改昵称。
    • 接口地址:https://accounts.extstars.com/api/v2/auth/change_username
    • 请求方法:POST
    • 接口参数格式:
      • user_name={new_username}
    • 接口返回参数:
      • code=100 操作成功
  • 6、激活接口
    • 接口名称:激活 APP。
    • 接口用途:用于 激活 APP。
    • 接口地址:https://accounts.extstars.com/api/v2/code/active
    • 请求方法:POST
    • 接口参数格式:
      • code={code, 激活码}
      • device_id={device_id}
      • device_info={device_info}
    • 接口返回参数:
      • code=100 操作成功
      • code=101 激活码不存在
      • code=102 参数缺失
      • code=103 使用次数超限
      • code=104 已激活,无需激活
      • code=105 激活码还未生效或者已经过期
  • 7、反激活接口
    • 接口名称:反激活 APP。
    • 接口用途:用于 反激活 APP。
    • 接口地址:https://accounts.extstars.com/api/v2/code/deactive
    • 请求方法:POST
    • 接口参数格式:
      • device_id={device_id}
    • 接口返回参数:
      • code=100 操作成功
      • code=101 尚未激活
      • code=102 参数不全
      • code=103 不允许反激活
  • 8、获取激活信息接口
    • 接口名称:激活信息获取
    • 接口用途:用于 获取激活信息
    • 接口地址:https://accounts.extstars.com/api/v2/code/check
    • 请求方法:POST
    • 接口参数格式:
      • device_id={device_id}
      • 以下参数在特定情况下可选:
        • step_key={step_key},如果您上一次请求这个接口时得到了这个参数,那么请在此带上,否则该参数可省略。
    • 接口返回参数:
      • code=100 操作成功
        • data
          • key=验证key,在请求子系统时候带上
          • expire_in=上面这个 key 的过期时间戳
          • active_order=激活次序
          • score= 这个 App 里用户的积分
          • step_key=步骤 key,用于防滥用,请在下一次请求本接口时以这个字串作为参数。
      • code=101 尚未激活
      • code=102 参数不全
      • code=103  设备 id 防滥用限制
  • 8、更改头像接口
    • 接口名称:更改头像。
    • 接口用途:用于修改头像。
    • 接口地址:https://accounts.extstars.com/api/v2/auth/change_avatar
    • 请求方法:POST
    • 接口参数格式(form data):
      • avatar
        • 其中文件格式为 jpg,png
    • 接口返回参数:
      • code=100 操作成功
      • code=101 文件类型不允许
      • code=102 参数不全
  • 9、拉取论坛帖子
    • 接口名称:拉取论坛的帖子
    • 接口用途:用于 拉取论坛的帖子
    • 接口地址:https://accounts.extstars.com/api/v2/chat/pull
    • 请求方法:POST
    • 接口参数格式:
      • offset={起始位置(从 0 开始)}
      • limit={限制条目数}
      • 以下两个参数可选:出现则起效,不出现则维持
        • is_pin={0|1}(是否置顶)
        • plate_id={plate_id}(板块 ID)
    • 接口返回参数:
      • code=100 操作成功
        • data(以下为数组)
          • id={条目 id}
          • subject={标题}
          • created_at={创建时间}
          • updated_at={回复时间}
          • read_count={阅读次数}
          • user(单个)
            • user_name={user_name}
            • user_avatar={user_avatar_url}
            • user_role_type={用户角色数字}
            • user_score={用户积分}
            • user_has_active={true|false}
        • total=条目总数
      • code=102 参数不全
  • 10、拉取论坛帖子详情
    • 接口名称:拉取论坛的帖子详情
    • 接口用途:用于 拉取论坛的帖子详情
    • 接口地址:https://accounts.extstars.com/api/v2/chat/{thread_id}/pull
    • 请求方法:POST
    • 接口参数格式:
      • offset={起始位置(从 0 开始)}
      • limit={限制条目数}
    • 接口返回参数:
      • code=100 操作成功
        • data
          • thread_id={条目 id}
          • subject={标题}
          • created_at={创建时间}
          • updated_at={回复时间}
          • read_count={阅读次数}
          • user( 单个)
            • user_name={user_name}
            • user_avatar={user_avatar_url}
            • user_role_type={用户角色数字}
            • user_score={用户积分}
            • user_has_active={true|false}
          • posts(以下为数组)
            • post_id={条目 id}
            • body={内容}
            • created_at={创建时间}
            • updated_at={回复时间}
            • like_count={被点赞次数}
            • user(单个)
              • user_name={user_name}
              • user_avatar={user_avatar_url}
              • user_role_type={用户角色数字}
              • user_score={用户积分}
              • user_has_active={true|false}
          • total_post=post 条目总数
      • code=102 参数不全
  • 11、发帖
    • 接口名称:发帖
    • 接口用途:用于 进行发帖和恢复操作
    • 接口地址:https://accounts.extstars.com/api/v2/chat/create
    • 请求方法:POST
    • 接口参数格式:
      • subject={subject}
      • body={body}
      • 以下参数可选
        • plate_id={板块 ID}
    • 接口返回参数:
      • code=100 操作成功
        • data
          • thread_id={条目 id}
          • subject={标题}
          • created_at={创建时间}
          • updated_at={回复时间}
          • read_count=0
          • user( 单个)
            • user_name={user_name}
            • user_avatar={user_avatar_url}
            • user_role_type={用户角色数字}
            • user_score={用户积分}
            • user_has_active={true|false}
          • posts(以下为数组)
            • post_id={条目 id}
            • body={内容}
            • created_at={创建时间}
            • updated_at={回复时间}
            • user(单个)
              • user_name={user_name}
              • user_avatar={user_avatar_url}
              • user_role_type={用户角色数字}
              • user_score={用户积分}
              • user_has_active={true|false}
          • total_post=post 条目总数
      • code=102 参数不全
  • 12、回复帖子
    • 接口名称:发帖
    • 接口用途:用于 进行发帖和恢复操作
    • 接口地址:https://accounts.extstars.com/api/v2/chat/{thread_id}/create
    • 请求方法:POST
    • 接口参数格式:
      • body={body}
    • 接口返回参数:
      • code=100 操作成功
      • code=101 thread 不存在
      • code=102 参数不全
  • 13、点赞帖子 post
    • 接口名称:点赞 post
    • 接口用途:用于 给 post 进行点赞
    • 接口地址:https://accounts.extstars.com/api/v2/chat/{thread_id}/post/{post_id}/like
    • 请求方法:POST
    • 接口返回参数:
      • code=100 操作成功
      • code=101 post 不存在
      • code=102 参数不全
  • 14、反点赞帖子 post
    • 接口名称:反点赞 post
    • 接口用途:用于 给 post 进行反点赞
    • 接口地址:https://accounts.extstars.com/api/v2/chat/{thread_id}/post/{post_id}/dislike
    • 请求方法:POST
    • 接口返回参数:
      • code=100 操作成功
      • code=101 post 不存在
      • code=102 参数不全
  • 15、子系统积分令牌获取
    • 接口名称:子系统积分令牌获取
    • 接口用途:用于子系统积分令牌获取
    • 接口地址:https://accounts.extstars.com/api/v2/score/challenge/create
    • 请求方法:POST
    • 接口请求参数:
      • api_route={完整的 API 路径,包括 https://}
    • 接口返回参数:
      • code=100 操作成功
        • data
          • expire_in=过期时间
          • token={用于请求子系统时在 HTTP  头带上}
      • code=101 没有相应的积分策略
      • code=102 参数不全
  • 16、子系统积分令牌验证
    • 接口名称:子系统积分令牌验证
    • 接口用途:用于子系统积分令牌验证,验证之后可以得到相应的分数
    • 接口地址:https://accounts.extstars.com/api/v2/score/challenge/check
    • 请求方法:POST
    • 接口请求参数:
      • token={从子系统请求里得到的 ScoreToken  头内容}
    • 接口返回参数:
      • code=100 操作成功
        • data
          • add_score= 加分数目
      • code=101 没有相应的积分策略
      • code=102 参数不全
      • code=103 token错误
      • code=104  解析时出现错误
      • code=105 Appid  不符
      • code=106 用户 ID 不符
      • code=107 重放检测
      • code=108 令牌过期
  • 17、创世用户校验
    • 接口名称:创世用户校验
    • 接口用途:用于创世用户校验
    • 接口地址:https://accounts.extstars.com/api/v2/code/starter/first
    • 请求方法:GET
    • 接口返回参数:
      • code=100 操作成功,第一次校验
      • code=101 未激活
      • code=102 激活了,但不是创世用户
      • code=103 是创世用户,但这个激活码被校验过了
      • code=104  是创世用户,但这个用户已经校验过了
  • 18、激活记录列表
    • 接口名称:激活记录列表
    • 接口用途:用于创世用户校验
    • 接口地址:https://accounts.extstars.com/api/v2/code/devices/pull
    • 请求方法:GET
    • 接口返回参数:
      • code=100  操作成功
        • data 以下为数组,返回已激活列表
          • id= 记录 id
          • app_id=  当前 app id
          • app_coed_id=  当前激活码 id
          • app_code_txt= 当前激活码文本
          • user_id=  用户 id
          • user_device_id= 用户设备id
          • user_device_info=用户设备描述文本
          • created_at=创建时间
          • updated_at=更新时间
          • deleted_at=删除时间
          • app_code_active_order=激活次序
  • 19、用户登出
    • 接口名称:用户登出接口
    • 接口用途:用于用户登出。
    • 接口地址:https://accounts.extstars.com/api/v2/auth/logout
    • 请求方法:GET
    • 接口参数:
    • 接口返回格式:
      • 1.code={code}
        • code=100  操作成功
  • 20、拉取论坛板块
    • 接口名称:拉取论坛的板块
    • 接口用途:用于 拉取论坛的板块
    • 接口地址:https://accounts.extstars.com/api/v2/chat/plate/list
    • 请求方法:POST
    • 接口参数格式:无
    • 接口返回参数:
      • code=100 操作成功
        • data(以下为数组)
          • id={条目 id}
          • app_id={APP ID}
          • plate_name={版块名称}
          • plate_order={板块顺序,拉取时已按此顺序将序排列}
          • created_at={创建时间}
          • updated_at={更新时间}
          • deleted_at={删除时间}
  • 21、拉取我的帖子
    • 接口名称:拉取我的论坛帖子
    • 接口用途:用于 拉取论坛我的帖子
    • 接口地址:https://accounts.extstars.com/api/v2/chat/mine/pull
    • 请求方法:POST
    • 接口参数格式:
      • offset={起始位置(从 0 开始)}
      • limit={限制条目数}
      • 以下两个参数可选:出现则起效,不出现则维持
        • is_pin={0|1}(是否置顶)
        • plate_id={plate_id}(板块 ID)
    • 接口返回参数:
      • code=100 操作成功
        • data(以下为数组)
          • id={条目 id}
          • subject={标题}
          • created_at={创建时间}
          • updated_at={回复时间}
          • read_count={阅读次数}
          • user(单个)
            • user_name={user_name}
            • user_avatar={user_avatar_url}
            • user_role_type={用户角色数字}
            • user_score={用户积分}
            • user_has_active={true|false}
        • total=条目总数
      • code=102 参数不全
  • 22、拉取我的新回复帖子
    • 接口名称:拉取我的有新回复论坛帖子
    • 接口用途:用于 拉取论坛我的有新回复帖子
    • 接口地址:https://accounts.extstars.com/api/v2/chat/new_reply/pull
    • 请求方法:POST
    • 接口参数格式:
      • offset={起始位置(从 0 开始)}
      • limit={限制条目数}
      • 以下两个参数可选:出现则起效,不出现则维持
        • is_pin={0|1}(是否置顶)
        • plate_id={plate_id}(板块 ID)
    • 接口返回参数:
      • code=100 操作成功
        • data(以下为数组)
          • id={条目 id}
          • subject={标题}
          • created_at={创建时间}
          • updated_at={回复时间}
          • read_count={阅读次数}
          • user(单个)
            • user_name={user_name}
            • user_avatar={user_avatar_url}
            • user_role_type={用户角色数字}
            • user_score={用户积分}
            • user_has_active={true|false}
        •  last_read_time={ 上一次阅读时间}
        • current_time={当前时间}
      • code=102 参数不全
  • 23、更改头像接口 base64
    • 接口名称:更改头像。
    • 接口用途:用于以 BASE64 修改头像。
    • 接口地址:https://accounts.extstars.com/api/v2/auth/change_avatar/base64
    • 请求方法:POST
    • 接口参数格式:
      • data={头像 base64 编码}
    • 接口返回参数:
      • code=100 操作成功
      • code=102 参数不全
  • 24、拉取搜索到的帖子
    • 接口名称:拉取搜索到的论坛帖子
    • 接口用途:用于 拉取搜索到的帖子
    • 接口地址:https://accounts.extstars.com/api/v2/chat/search/pull
    • 请求方法:POST
    • 接口参数格式:
      • offset={起始位置(从 0 开始)}
      • limit={限制条目数}
      • keyword={ 关键词}
      • 以下参数可选:出现则起效,不出现则维持
        • plate_id={plate_id}(板块 ID)
    • 接口返回参数:
      • code=100 操作成功
        • data(以下为数组)
          • id={条目 id}
          • subject={标题}
          • created_at={创建时间}
          • updated_at={回复时间}
          • read_count={阅读次数}
          • user(单个)
            • user_name={user_name}
            • user_avatar={user_avatar_url}
            • user_role_type={用户角色数字}
            • user_score={用户积分}
            • user_has_active={true|false}
        •  last_read_time={ 上一次阅读时间}
        • current_time={当前时间}
      • code=102 参数不全