星空辽阔账号系统 API

glzjin

6 年前

作者：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 参数不全