Skip to content
This repository was archived by the owner on Jul 16, 2025. It is now read-only.

【后端】 API 交互协议

Jump to bottom
Suvan edited this page Mar 14, 2018 · 61 revisions

目录

测试账号

  • ahonn-123456
  • AnAndroidXiang-123456
  • kayye-123456
  • topLynch-123456
  • Nancyshan-123456
  • suvan-123456

账号

登录

requestUrl = "http://localhost:8080/api/account/login"
method = "POST"
authentication:
prompt: 
     a. username（支持用户名 or 邮箱[必须符合格式] 登录）
     b. 自动登陆（可在 neubbs.properties 文件配置，默认 365 天）
     c. 客户端需支持 Cookie，以便储存 Authentication Token

request-body {
   "username": "",    //必选，用户名
   "password": ""     //必选，用户密码
}
response{
    success: true,
    message: ""
    model:{
         "authentication": ""    //用户认证加密信息（前后端校验）
         "state": ,               /boolean，账户激活状态（true-已激活，false-未激活）  
    }
}

注销

requestUrl = "http://localhost:8080/api/account/logout"
method = "GET"
authentication: @LoginAuthentication   //登录验证
prompt：用户需登录，才能注销

response {
    success: true,
    message: "",
    model: {}
}

注册

requestUrl = "http://localhost:8080/api/account/register"
method = "POST"

request-body {
    "username": "",    //必选，用户名
    "password": "",    //必选，用户密码
    "email": ""        //必选用户邮箱
}
response {
    success: true,
    message: "",
    model:{
            "username": "",      //用户名
            "email": "",         //邮箱
            "sex":  ,            //int, 性别（-1 无填写，0-女，1-男）
            "birthday": "",      //出生年月日
            "position": "",      //所在地
            "description": "",   //描述
            "avator": "",        //用户头像地址（默认头像 http 地址）  
            "state": ,           //int，激活状态
            "createtime": ""     //注册时间
    }
}

修改用户基本信息

requestUrl = "http://localhost:8080/api/account/update-profile"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation 
prompt: 
     a. 默认修改已登录用户用户
     b. sex 是数字类型，必定输入 （0-女，1-男）
     c. birthday, position, description 支持输入 "" 和 null
     d. model 返回的是最新的用户数据

request-body {
   "sex":  ,          //必选，int，用户性别(0-女，1-男)（length == 1）
   "birthday": "",    //必选，String，用户出生年月日（0 <= length <= 20）
   "position": "",    //必选，String，用户所在地 （0 <= length <= 255）
   "description": ""  //必选，String，个人描述 （0 <= length <= 255）
}
response {
    success: true,
    message: "",
    model: {
          "email": "",        //用户邮箱
          "sex":  ,            //int, 性别（-1 无填写，0-女，1-男）
          "birthday": "",     //用户出生年月日
          "position": "",     //用户所在地
          "description": "",  //用户个人描述
          "avator": "",       //用户头像 http 地址
          "state":            //boolean，用户激活状态（true-已激活，false-未激活）
          "createtime": "",   //创建时间（格式：时间戳）
          “userid"： ,         //int, 用户 id
          "username": ""     //用户名
     }
}

修改密码

requestUrl = "http://localhost:8080/api/account/update-password"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation 

request-body {
   "username": "",   //用户名
   "password": ""    //用户密码
}
response {
    success: true,
    message: "",
    model: {}
}

修改邮箱

requestUrl = "http://localhost:8080/api/account/update-email"
method = "POST"
authentication: @LoginAuthorization

request-body {
   " {"username":"","email":""} "     //JSON String
}
response {
    success: true,
    message: "",
    model: {}
}

账户激活

requestUrl = "http://localhost:8080/api/account/activate"
method = "POST"
prompt： 
      a.同用户发送激活邮件间隔 60s
      b.重复调用接口会提示 {success: false; message: wait for timer; model: {...} }
        且出现 $.model.timer，表示同用户下次发送邮件剩余时间

request-body {
     "email": ""         //必选要激活的邮箱（对应用户邮箱）
}
response {
    success: true,
    message: "",
    model: {
       timer: ;     //int, 重复发送邮件倒计时（同用户 60s 间隔）
    }
}

激活账户

requestUrl = "http://localhost:8080/api/account/validate"
method = "GET"

request-params {
    token: ""     //激活用户密文（激活邮件中 token）
}
response {
    success: true,
    message: "",
    model: {}
}

图片验证码

requestUrl = "http://localhost:8080/api/account/captcha"
method = "GET"
prompt： 页面生成图片验证码（.jpeg）, 并将验证码文本暂存到 Session

response-image {
   captcha.jpeg    //页面仅展示图片验证码
}

校验验证码

requestUrl = "http://localhost:8080/api/account/validate-captcha"
method = "GET"
prompt： 请根据 /api/account/captcha 接口生成验证码图片，根据图片输入相应验证码

request-param {
    captcha: ""    //必选，验证码文本
}
response-image {
    success: true,
    message: ""，
    model: {}
}

忘记密码

requestUrl = "http://localhost:8080/api/account/forget-password"
method = "POST"
prompt: 
      a. 调用该接口，自动修改用户密码为 5 位临时随机密码
      b. 同时向用户发送邮件，提示密码已经修改为临时密码(邮件包含临时密码)
      c. 重新登陆后，前端页面需提示用户主动修改密码

request-body {
    "email": ""         //必选，用户邮箱
}
response {
    success: true,
    message: "",
    model: {}
}

获取用户信息

requestUrl = "http://localhost:8080/api/account"
method = "GET"
prompt:
    a.username（支持 用户名 or 邮箱）
    b.username 和 email 至少输入其一（二选一即可，若同时输入，username 优先）

request-params {
      username: "",         //可选，用户名
      email: ""             //可选，用户邮箱
}
response {
    success: true,         //true-用户存在，false-用户不存在
    message: "",
    model:{    
          "email": "",        //邮箱
          "sex":  ,           //int, 性别（-1 无填写，0-女，1-男）
          "birthday": "",     //出生年月日
          "position": "",     //所在地
          "description": "",  //个人描述
          "avator": "",       //用户头像网络地址
          "state": ""         //int，用户激活状态（1-已激活，2-未激活）
          "createtime": "",   //创建时间（格式：时间戳）
          "username": "",     //用户名
          "userid": ,         //int, 用户 id
          "following":  ,     //int, 用户主动关注人数
          "followed": ,       //int, 用户粉丝数
          "like":  ,          //int, 用户喜欢话题数
          "collect":  ,       //int，用户收藏话题数
          "attention":  ,     //int，用户关注话题数
          "topic": ,          //int，用户发布话题数  
          "reply": ,          //int, 用户发布回复数   
    }
}

获取用户激活状态

requestUrl = "http://localhost:8080/api/account/state"
method = "GET"
prompt:
    a.username（支持 用户名 or 邮箱）

request-params {
   username: ""      //必选，用户名
}
response{
    success: true,   //true-用户已激活，false-用户未激活
    message: ""，
    model: {}
}

获取所有主动关注人信息

requestUrl = "http://localhost:8080/api/account/following"
method = "GET"

request-params {
    userid:  ,          //int，必选，用户 id,
}
response {
    success: true,
    message: ""，
    model: [
         - {
              "email": "",        //邮箱
              "sex":  ,           //int, 性别（-1 无填写，0-女，1-男）
              "birthday": "",     //出生年月日
              "position": "",     //所在地
              "description": "",  //个人描述
              "avator": "",       //用户头像网络地址
              "state": ""         //boolean，用户激活状态（true-已激活，false-未激活）
              "createtime": "",   //创建时间（格式：时间戳）
              "userid":           //int, 用户 id
              "username": "",     //用户名
           },
           {
              ......
           }
         ]
}

获取所有粉丝信息

requestUrl = "http://localhost:8080/api/account/followed"
method = "GET"

request-params {
    userid:  ,          //int，必选，用户 id,
}
response {
    success: true,
    message: ""，
    model: [
         - {
              "email": "",        //邮箱
              "sex":  ,           //int, 性别（-1 无填写，0-女，1-男）
              "birthday": "",     //出生年月日
              "position": "",     //所在地
              "description": "",  //个人描述
              "avator": "",       //用户头像网络地址
              "state": ""         //boolean，用户激活状态（true-已激活，false-未激活）
              "createtime": "",   //创建时间（格式：时间戳）
              "userid":           //int, 用户 id
              "username": "",     //用户名
           },
           {
              ......
           }
         ]
}

关注用户

requestUrl = "http://localhost:8080/api/account/following"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation
prompt:
     a. 自动注入当前已登陆用户信息
     b. 自动取反（已关注 -> 未关注， 未关注 -> 已关注）

request-body {
    "userid":  ,          //必选，int，用户 id,
}
response {
    success: true,
    message: ""，
    model: {
        followingUserId:[]    //当前用户主动关注用户 id 列表
    }
}

话题

获取话题信息

requestUrl = "http://localhost:8080/api/topic"
method = "GET"
prompt: jadread 参数可选，若不输入此参数默认为 0，不增加阅读量

request-params {
    "topicid": "",            //必选，话题id
    "hadread": "",            //可选，是否增加阅读数（0-不增加，1-增加），
}
response {
    success: true,
    message: ""
    model {
        "title:"："",          //标题
        "replies": ,           //int, 回复数
        "lastreplytime": "",   //最后回复时间（格式：时间戳），若无回复，默认为发表时间
        "createtime": ""，     //发表时间（格式：时间戳）
        "topicid": ,           //int, 话题id
        "content": "",         //回复内容
        "read":  ,             //int, 阅读数
        "like": ,              //int, 喜欢人数
        - category {
            "id": "",          //话题昵称（英文）
            "name": ""         //话题名称（中文）
         }
        - user {
            "avator": ""       //发表人头像地址
            "username": ""     //发表人用户名
        }
        - lastreplyuser {
           "avator": ""       //最后回复人头像地址
           "username": ""     //最后回复人用户名
        }
        - replylist{      //回复信息列表
            -{
                "topicid": ,         //int，对应话题 id
                "content": "",       //回复内容
                "agree":  ,          //int，点赞数,
                "oppose": ,          //int，反对数
                "createtime": ""     //发表时间（格式：时间戳）
                "replyid": ,         //int，该回复 id
                - user {
                    "avator": ""，     //发表回复用户头像地址
                    "username": ""   //发表回复用户名
                }
             },
            -{
                ...
             }
        }
        - isliketopic:   //boolean, 判断当前用户是否喜欢话题（true-喜欢，false-不喜欢）
    }
}

获取热议话题列表

requestUrl = "http://localhost:8080/api/topics/hot"
method = "GET"
prompt: 
   a. 当天评论数最多的 10 条话题信息（优先当天分组，其次话题回复数分组）
   b. 若当天不足 10 条，则以前一天的热议话题补充，以此类推

response {
    success: true,
    message: ""
    model {  //话题列表
        -{
             "title:"："",          //标题
             "replies"："",         //int，回复数
             "lastreplytime": "",   //最后回复时间（格式：时间戳），若无回复，则为0
             "createtime":"",       //发表时间（格式：时间戳）
             "topicid": ,           //int，话题id
             - category {
                  "id": "",         //String，话题昵称，显示层 id
                  "name": ""        //话题名称
              }
             - user {
                  "avator": "",       //发表人头像地址
                  "username": ""      //发表人用户名
              }
             - lastreplyuser {
                  "avator": "",       //最后回复人头像地址
                  "username": ""      //最后回复人用户名
             }
         },
        -{
         ...
         }
     }
}

获取首页话题列表

requestUrl = "http://localhost:8080/api/topics"
method = "GET"
prompt: 
   a. 必须输入 page 参数, 指定跳转页数
   b. limit 具备默认值（默认是 25, 可修改  resources/neubbs.properties 项目配置文件）
   c. 可同时输入 category 和 username 作为筛选条件
   d. 若输入了 category 参数，$.model 不会显示 category 相关信息，username 同理

request-params {
    limit: "",        //可选，每页显示数量
    page: "",         //必须，跳转到指定页数
    category: "",     //可选，话题昵称，先是层 id（英文)
    username: ""      //可选，用户名
}
response {
    success: true,
    message: ""
    model {  //话题列表
        -{
             "title:"："",          //标题
             "replies"："",         //int，回复数
             "lastreplytime": "",   //最后回复时间（格式：时间戳），若无回复，则为0
             "createtime":"",       //发表时间（格式：时间戳）
             "topicid": ,           //int，话题id
             "content": "",         //回复内容
             "read":  ,             //int，阅读数
             "like": ,              //int，点赞数
             - category {
                  "id": "",         //String，话题昵称，显示层 id(英文)
                  "name": ""        //话题名称
              }
             - user {
                  "avator": "",       //发表人头像地址
                  "username": ""      //发表人用户名
              }
             - lastreplyuser {
                  "avator": "",       //最后回复人头像地址
                  "username": ""      //最后回复人用户名
             }
         },
        -{
         ...
         }
     }
}

获取回复信息

requestUrl = "http://localhost:8080/api/reply"
method = "GET"

request-params {
    "replyid": "",           //必选，回复 id
}
response {
    success: true,
    message: ""
    model {
        "topicid": ,         //int, 对应话题 id
        "content": "",       //回复内容
        "agree":  ,          //点赞数,int
        "oppose": ,          //反对数，int
        "createtime", ""     //发表时间（格式：时间戳）
        "replyid": ,         //int, 当前回复 id
        - user{
             "avator": "",         //用户头像地址
             "username": "",       //发表回复用户名
         }
     }
}

获取话题总页数

requestUrl = "http://localhost:8080/api/topics/pages"
method = "GET"
prompt:
   a. limit 具备默认值（默认是 25, 可修改  resources/neubbs.properties 项目配置文件）
   b.支持同时输入 category 和 username 作为筛选条件

request-params {
    "limit": "",           //可选，每页显示数量
    "category", "",        //可选，话题昵称，先是层 id（英文)
    "username", ""         //可选，用户名
}
response {
    success: true,
    message: ""
    model {
       "totalpages":     //int，话题总页数
    }
}

获取所有话题分类

requestUrl = "http://localhost:8080/api/topics/categorys"
method = "GET"

response {
    success: true,
    message: ""
    model {
       - {
             "id": "",    //String，话题昵称，显示层 id
             "name": ""   //话题名称
         },
       - {
             "id": "",
             "name": ""
         }
       - {
           ...
         }
         
        ......
    }
}

发布话题

requestUrl = "http://localhost:8080/api/topic"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation

request-body {
     "category": "",         //必选，话题昵称，显示层 id（英文）
     "title": "",            //必选，话题标题（1 <= length <= 50）
     "content": ""           //必选，话题内容（1 <= length <= 100000 十万）
}
response {
    success: true,
    message: ""
    model:{
       topicid: ,            //int，新发布的话题 id
    }
}

发布回复

requestUrl = "http://localhost:8080/api/topic/reply"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation

request-body {
   "{
      "topicid": ,           //必选，int，话题id
      "content": ""          //必选，回复内容（1 <= length <= 150）
   }"
}
response {
    success: true,
    message: ""
    model:{
       replyid: ,            //int，回复 id
    }
}

删除话题

requestUrl = "http://localhost:8080/api/topic-remove"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation, @AdminRank

request-body {
    "topicid": ,           //必选，int, 话题id 
}
response {
    success: true,
    message: "",
    model: {}
}

删除回复

requestUrl = "http://localhost:8080/api/reply-remove"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation, @AdminRank

request-body {
    "replyid": ,           //必选，int, 回复id
}
response {
    success: true,
    message: "",
    model: []
}

修改话题内容

requestUrl = "http://localhost:8080/api/topic-update"
method = "POST"
authentication: @LoginAuthorization， @AccountActivation

request-body {
      "topicid": ,           //必选，int, 话题id
      "category": ""         //必选，新话题分类昵称，显示层 id（英文）
      "title": "",           //必选，（1 <= length <= 50）
      "content": ""          //必选，话题内容（1 <= length <= 100000 十万）
}
response {
    success: true,
    message: ""，
    model: {}
}

修改回复内容

requestUrl = "http://localhost:8080/api/topic/reply-update"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation

request-body {
    "replyid": ,           //必选，int，回复id,
    "content": ""          //必选，新回复内容（1 <= length <= 150）
}
response {
    success: true,
    message: "",
    model: {}
}

点赞话题-旧

requestUrl = "http://localhost:8080/api/topic/like"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation
prompt: 
     a. 只接收命令 "inc" 和 "dec" ，输入其他命令会提示错误 'incorrect input parameter'
     c. 命令小写，请勿大写，且为字符串格式
     d. 若已登录用户，已经点赞过该话题，不能重复点赞（取消操作亦是如此，会返回错误信息）

request-body {
    "topicid":  ,          //必选，int，话题 id,
    "command": ""          //必选，输入命令（inc - 自增1，dec - 自减1）
}
response {
    success: true,
    message: ""，
    model: {
        like:  ,           //int，根据命令操作后，当前话题最新喜欢人数
    }
}

点赞话题-新

requestUrl = "http://localhost:8080/api/topic/newlike"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation
prompt: 
     a.自动注入当前用户信息
     b.自动处理用户喜欢话题状态，取反（已喜欢 -> 未喜欢， 未喜欢 -> 已喜欢）
     c.旧版点赞接口未取消，暂时未合并（功能一致，新版无须输入 command）

request-body {
    "topicid":  ,          //必选，int，话题 id,
}
response {
    success: true,
    message: ""，
    model: {
        userLikeTopicId:[]     //当前用户已点赞话题 id 列表
        like:                  //int，当前话题最新喜欢人数
    }
}

收藏话题

requestUrl = "http://localhost:8080/api/topic/collect"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation
prompt:
     a.自动注入当前用户信息
     b.自动处理用户收藏话题状态，取反（已收藏 -> 未收藏， 未收藏 -> 已收藏）

request-body {
    "topicid":  ,          //必选，int，话题id,
}
response {
    success: true,
    message: ""，
    model: {
        userCollectTopicId:[]    //当前用户已收藏话题 id 列表
    }
}

关注话题

requestUrl = "http://localhost:8080/api/topic/attention"
method = "POST"
authentication: @LoginAuthorization，@AccountActivation
prompt: 
     a.自动注入当前用户信息
     b.自动处理用户关注话题状态，取反（已关注 -> 未关注， 未关注 -> 已关注）

request-body {
    "topicid":  ,          //必选，int，话题id,
}
response {
    success: true,
    message: ""，
    model: {
        userAttentionTopicId:[]    //当前用户已关注话题 id 列表
    }
}

论坛基数统计

requestUrl = "http://localhost:8080/api/count"
method = "GET"

response{
    success: true,
    message: "",
    model: {
        user:  ,     //int，用户总数
        topic: ,     //int，话题总数
        reply: ,     //int，回复总数
    }
}

客户端在线统计

requestUrl = "http://localhost:8080/api/count/online"
method = "GET"
prompt: 
     a.实时监控
     b.访客用户和论坛登陆用户，不重复

response{
    success: true,
    message: "",
    model: {
        visitUser:  //int，在线访问人数（未登录）
        loginUser:  //int, 在线登陆人数（已登陆）
    }
}

用户统计

requestUrl = "http://localhost:8080/api/count/user"
method = "GET"

request-param {
    userid:  ,      //int, 必选，用户 id
}
response {
    success: true,
    message: "",
    model: {
          "following":  ,     //int, 用户主动关注人数
          "followed": ,       //int, 用户粉丝数
          "like":  ,          //int, 用户喜欢话题数
          "collect":  ,       //int，用户收藏话题数
          "attention":        //int，用户关注话题数
          "topic": ,          //int，用户发布话题数   
          "reply": ,          //int, 用户发布回复数
    }
}

文件

上传用户头像

requestUrl = "http://localhost:8080/api/file/avator"
method = "POST"
authentication: @LoginAuthorization @AccountActivation

enctype= "multipart/form-data"   // html 表单需添加此属性
html-form-input {
    <form action="api/file/upload-user-image" enctype="multipart/form-data" method="post">
        <input type="file" name="image">   // 此处：name = "avatorImage"
        <input type="submit">
    </form>
}

response {
    success: true,
    message: ""
}

Clone this wiki locally