跳转至

内部API接口

接口概述

本接口文档描述的是 是黑羽学院系统 前端 和 后端子系统之间的内部接口。

所有的HTTP请求响应消息，如果有消息体，一律为json格式。

所有的API响应消息，如果操作 不成功，返回消息体 格式如下

{
    "ret": 1,    
    "msg":  "用户名或者密码错误"
}

ret 不为 0 表示操作失败， msg 字段描述 API 操作失败的原因


登录

3种类型的账号：管理员、老师、学生， 均使用该接口进行登录。

前端发送的登录请求中包含账号、密码。

后端接收后，对账号密码的正确性进行校验。

HyLearn 系统使用session会话机制。

如果校验通过，服务端在响应消息头Set-Cookie 中存入sessionid ，该用户的后续请求头Cookie中必须携带sessionid。

请求

  • 请求头
POST /api/sign
Content-Type: application/json
  • 消息体

为json格式

{
    "action" : "signin",
    "username" : "xxxx",
    "password" : "yyyy"
}

action 字段值为 signin 表示登录

username 字段值为登录账号的用户名

password 字段值为登录账号的密码

响应

  • 响应头
200 OK
Content-Type: application/json
Set-Cookie: sessionid=<sessionid数值>
  • 消息体

如果校验通过，返回消息如下

{
    "ret": 0,
    "usertype":1,
    "userid":1,
    "realname":"白月黑羽",
}

ret 为 0 表示登录成功

usertype 是用户类型。 1：超级管理员，8888：其他类型

userid 是用户在系统中的id

realname 是用户的姓名

登录成功后， 服务端在消息头Set-Cookie 中存入sessionid ，该用户的后续请求头Cookie中必须携带sessionid。


如果登录校验失败，返回失败的原因，示例如下

{
    "ret": 1,    
    "msg":  "用户名或者密码错误"
}

ret 不为 0 表示登录失败， msg字段描述登录失败的原因

登出

请求

  • 请求头
POST /api/sign
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

为json格式

{
    "action" : "signout"
}

action 字段值为 signout 表示退出登录

响应

后端应该根据sessionid清除掉session，然后返回响应消息

  • 响应头
200 OK
Content-Type: application/json
Set-Cookie: sessionid=""
  • 消息体
{
    "ret": 0
}

账号管理

该API接口 用来 列出、添加、修改、删除系统中的账号。

发出账号管理的API 只能是管理员用户。后端要根据session校验。

账号管理的API 路径均为 /api/account

列出账号

用来列出系统中的账号信息。

请求

  • 请求头
GET /api/account?action=listbypage&pagenum=1&pagesize=5&keywords=
Cookie: sessionid=<sessionid数值>
  • url参数
参数名 示例 必要性 含义
action listbypage 必填项 必须为 listbypage
pagesize 3 必填项 分页的 每页获取多少条记录
pagenum 2 必填项 获取第几页的信息
keywords 白月 黑 可选项 搜索关键字，如果提供，表示用户姓名中包含的关键字。 多个关键字以空格隔开，表示姓名中同时包含的关键字词

响应

后端返回列出结果

  • 消息体
{
  "ret": 0,
  "items": [
    {
      "id": 4,
      "username": "student-4",
      "realname": "学生-4",
      "desc": "学生-4",
      "usertype": 8888
    },
    {
      "id": 3,
      "username": "student-3",
      "realname": "学生-3",
      "desc": "学生-3",
      "usertype": 8888
    },
    {
      "id": 2,
      "username": "student-2",
      "realname": "学生-2",
      "desc": "学生-2",
      "usertype": 8888
    },
  ],
  "total": 8,
  "keywords": ""
}

ret 为 0 表示列出成功

total 为 8 表示系统中（不是当前页）总共有8个账号

items 数组 里面包含了当前页中的账号信息。

每个账号信息以如下格式存储

    {
      "id": 2,
      "username": "student-2",
      "realname": "学生-2",
      "desc": "学生-2",
      "usertype": 8888
    },

添加账号

用来添加系统中的账号信息。

请求

  • 请求头
POST /api/account
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

要添加的账号的具体信息，格式如下

{
  "action": "addone",
  "data": {
    "realname" : "紫一元",
    "username" : "ziyiyuan",
    "password" : "111111",
    "desc"     : "白月黑羽的优秀学员",
    "usergroup": [1,2],
    "permission":[23,22,21]
  }
}

其中

action： 填写 addone， 表示 添加一个账号的操作

realname： 用户的姓名

username： 用户的登录名

password： 用户的密码

desc： 账号描述信息

usergroup： 可选项，以数组的方式指定 该用户所属的用户组对应的id。 目前创作者 组id 固定为1， 创造管理 组id 固定为2

permission： 可选项，以数组的方式指定 该用户所拥有权限 对应的id

响应

  • 消息体
{
  "ret": 0,
  "id": 5
}

ret 为 0 表示添加成功

id 为添加账号的 id

修改账号

用来修改系统中的账号信息。

请求

  • 请求头
PUT /api/account
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

要修改的账号的具体信息，格式如下

{
  "action": "modifyone",
  "id": 10,
  "newdata": {
    "realname": "紫一元2",
    "username": "ziyiyuan2",
    "password": "111111",
    "desc": "白月黑羽网站的Python老师，创业公司CTO",
    "usergroup": [2,1],
    "permission":[23,22,21]
  }
}

其中

action： 填写 modifyone ，表示 修改一个账号的操作

id： 要修改账号的 id

newdata ： 里面包含了要修改的信息

realname： 用户的姓名修改为什么。如果此项不用修改，该字段不出现

username： 用户的登录名修改为什么。如果此项不用修改，该字段不出现

password： 用户的密码修改为什么。如果此项不用修改，该字段不出现

desc： 账号的描述信息修改为什么。如果此项不用修改，该字段不出现

usergroup： 以数组的方式指定 该用户所属的用户组对应的id。如果此项不用修改，该字段不出现

permission： 以数组的方式指定 该用户所拥有权限 对应的id。如果此项不用修改，该字段不出现

响应

  • 消息体
{
  "ret": 0
}

ret 为 0 表示修改成功

删除账号

用来删除系统中的账号信息。

请求

  • 请求头
DELETE /api/account
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

格式如下

{
  "action": "deleteone",
  "id": 10
}

其中

action： 填写 deleteone ，表示 删除 一个账号的操作

id： 要删除账号的 id

响应

  • 消息体
{
  "ret": 0
}

ret 为 0 表示删除成功

课程管理

添加课程

用来添加课程

请求

  • 请求头
POST /api/lesson
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

要添加的课程的具体信息，格式如下

{
  "action": "addone",
  "data": {
    "title": "自动化测试专题1",
    "usage": 1,
    "coverimage": "/upload/1_20210316174037_268543.png",
    "content": "自动化测试专题1",
    "videos": "[]",
    "price": "0",
    "categorytags": {
      "selectedCategoryIds": [1,2],
      "selectedTagIds": [3,4]
    }
  }
}

其中

action： 填写 addone， 表示 添加的操作

data 为修改课程的信息，其中：

title： 课程标题

usage： 用途， 0：只在专题中 ； 1： 可以独立展示

coverimage： 封面图片

content： 课程内容

videos： 课程包含的视频，数组格式

price： 课程价格

categorytags： 课程所属种类和标签

响应

  • 消息体
{
  "ret": 0,
  "id": 5
}

ret 为 0 表示添加成功

id 为添加课程的 id

列出课程

该API接口 给普通用户用来 列出 系统中的课程。

请求

  • 请求头
GET /api/lesson?action=listbypage&pagenum=1&pagesize=5&keywords=&withoutcontent=true&withuserstate=true&categorytags={"selectedCategoryIds":[52,59],"selectedTagIds":[34,21]}
Cookie: sessionid=<sessionid数值>
  • url参数
参数名 示例 必要性 含义
action listbypage 必填项 必须为 listbypage
pagesize 3 必填项 分页的 每页获取多少条记录
pagenum 2 必填项 获取第几页的信息
keywords 白月 黑 可选项 搜索关键字，如果提供，表示课程标题中包含的关键字。 多个关键字以空格隔开，表示同时包含的关键字词
withoutcontent true 可选项 如果出现，并且值为true 表示列出的课程信息不要包含课程content内容，这是为了节省不必要的流量
withuserstate true 可选项 如果出现，并且值为true 表示列出的课程信息 中，需要包括 当前用户对该产品的点赞，收藏、购买 状态
categorytags {"selectedCategoryIds":[52,59,57],"selectedTagIds":[34,21]} 可选项 json格式，要求列出的课程 所关联的 种类 和 标签， 本例中表示只列出所属种类ID 为 52或者59其中之一，并且关联标签ID 为34或者21

响应

后端返回列出结果

  • 消息体
{
  "ret":0,
  "total":321,
  "keywords":"",
  "items":[
    {
      "id":459,
      "pubdate":"2020-12-21T00:00:00Z",
      "author":32,
      "title":"牛顿力学-5",
      "status":1,
      "coverimage":"/upload/niu342774234.png",
      "thumbupcount":6727,
      "favorcount":4969,
      "price":"40",
      "purchasecount":0,
      "approved":1,
      "reviewcomments":"",
      "author_name":"teacher0030",
      "userstate":""
    },
    {
      "id":458,
      "pubdate":"2020-12-21T00:00:00Z",
      "author":32,
      "title":"牛顿力学-4",
      "status":1,
      "coverimage":"/upload/niu142774234.png",
      "thumbupcount":4794,
      "favorcount":3044,
      "price":"20",
      "purchasecount":0,
      "approved":1,
      "reviewcomments":"",
      "author_name":"teacher0030",
      "userstate":""
    },
    {
      "id":457,
      "pubdate":"2020-12-21T00:00:00Z",
      "author":32,
      "title":"牛顿力学-3",
      "status":1,
      "coverimage":"/upload/niu312774234.png",
      "thumbupcount":3155,
      "favorcount":4556,
      "price":"20",
      "purchasecount":0,
      "approved":1,
      "reviewcomments":"",
      "author_name":"teacher0030",
      "userstate":""
    },
    {
      "id":456,
      "pubdate":"2020-12-21T00:00:00Z",
      "author":32,
      "title":"牛顿力学-2",
      "status":1,
      "coverimage":"/upload/niu382774234.png",
      "thumbupcount":131,
      "favorcount":1421,
      "price":"40",
      "purchasecount":0,
      "approved":1,
      "reviewcomments":"",
      "author_name":"teacher0030",
      "userstate":""
    },
    {
      "id":455,
      "pubdate":"2020-12-21T00:00:00Z",
      "author":32,
      "title":"牛顿力学-1",
      "status":1,
      "coverimage":"/upload/niu452774234.png",
      "thumbupcount":8635,
      "favorcount":217,
      "price":"40",
      "purchasecount":0,
      "approved":1,
      "reviewcomments":"",
      "author_name":"teacher0030",
      "userstate":"thumbup|favorite|purchased|"
    }
  ]
}

ret 为 0 表示列出成功

total 为 321 表示系统中（不是当前页）总共有321个课程

items 数组 里面包含了当前页中的课程信息。

每个课程信息以如下格式存储，加上了注解

    {
      "id":455, # 课程ID
      "pubdate":"2020-12-21T00:00:00Z", # 创建日期
      "author":32,          # 创作者 ID
      "title":"牛顿力学-1",  # 课程名称
      "status":1,
      "coverimage":"/upload/niu342774234.png", # 封面图片
      "thumbupcount":8635, # 点赞数
      "favorcount":217,    # 收藏数
      "price":"40",        # 售价, 为 0 表示免费
      "purchasecount":0,   # 购买数量
      "approved":1,        # 批准状态    0: 待批准， 1： 批准， 2：待修改
      "reviewcomments":"", # 审核意见
      "author_name":"teacher0030", # 创作者姓名
      "userstate":"thumbup|favorite|purchased|"   # 当前用户对此课程使用信息
    },

其中 userstate 表示 当前用户对此课程 是否 点赞、收藏、购买

如果点赞， userstate 值中包含 thumbup| 如果收藏， userstate 值中包含 favorite| 如果购买， userstate 值中包含 purchased|

修改课程

用来修改课程的信息。

该API 只能是课程的发布者 或者 管理员 调用

请求

  • 请求头
PUT /api/lesson
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

修改的课程的API，格式如下

{
  "action": "modifyone",
  "id": 40,
  "newdata": {
    "title": "自动化测试专题1",
    "usage": 1,
    "coverimage": "/upload/1_20210316174037_268543.png",
    "content": "自动化测试专题1",
    "videos": "[]",
    "price": "0",
    "categorytags": {
      "selectedCategoryIds": [],
      "selectedTagIds": []
    }
  }
}

其中

action： 填写 modifyone 表示 修改操作

id 为要修改课程的id

newdata 为修改课程的信息，其中每个属性的含义和添加课程相同。 如果该属性没有修改，就不需要出现。

响应

  • 消息体
{
  "ret": 0,
  "approved": 0
}

ret 为 0 表示修改成功

approved 为当前课程的审核状态 0: 待批准， 1： 批准， 2：待修改。 因为课程一旦修改后，就会处于代审核批准状态

删除课程

用来删除课程。该接口只能管理员或课程的创作者调用

请求

  • 请求头
DELETE /api/lesson
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

格式如下

{
  "action": "deleteone",
  "id": 10
}

其中

action： 填写 deleteone ，表示 删除 一个 的操作

id： 要删除课程的 id

响应

  • 消息体
{
  "ret": 0
}

ret 为 0 表示删除成功

审核课程

用来审核课程，发布后，审核通过的课程，产品展示界面才能看不到。该接口只能是有审核权限的审核员调用

请求

  • 请求头
POST /api/lesson
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

格式如下

{
  "action": "reviewresult",
  "id": 42,
  "result": "pass",
  "comments": "很好"
}

其中

action： 填写 reviewresult ，表示 审核 的操作

id： 要 撤回课程的 id

result： 审核结果，只能填 pass 或者 modify， pass：通过， modify：不通过，打回修改

comments： 审核意见，可以为空

响应

  • 消息体
{
  "ret": 0
}

ret 为 0 表示 调用成功

撤回课程

用来撤回课程，撤回后的课程产品展示界面看不到。该接口只能课程的创作者调用

请求

  • 请求头
PUT /api/lesson
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

格式如下

{
  "action": "holdone",
  "id": 10
}

其中

action： 填写 holdone ，表示 撤回 的操作

id： 要 撤回课程的 id

响应

  • 消息体
{
  "ret": 0, 
  "status": 2
}

ret 为 0 表示 撤回成功 status 表示 当前的状态 1: 发布 2：草稿 3:封禁

封禁课程

用来封禁课程，封禁后的课程产品展示界面看不到。该接口只能管理员调用

请求

  • 请求头
PUT /api/lesson
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

格式如下

{
  "action": "banone",
  "id": 10
}

其中

action： 填写 banone ，表示 封禁 的操作

id： 要 封禁课程的 id

响应

  • 消息体
{
  "ret": 0, 
  "status": 3
}

ret 为 0 表示 封禁成功 status 表示 当前的状态 1: 发布 2：草稿 3:封禁

批准课程

用来批准课程，批准后的课程产品展示界面可以看到。该接口只能管理员调用

被封禁状态的课程，必须要批准，产品展示界面才可以看到

请求

  • 请求头
PUT /api/lesson
Cookie: sessionid=<sessionid数值>
Content-Type: application/json
  • 消息体

格式如下

{
  "action": "publishone",
  "id": 10
}

其中

action： 填写 publishone ，表示 批准发布 的操作

id： 要 批准 课程的 id

响应

  • 消息体
{
  "ret": 0, 
  "status": 1
}

ret 为 0 表示 发布 成功 status 表示 当前的状态 1: 发布 2：草稿 3:封禁

专题管理

该API接口 给普通用户用来 列出 系统中的专题。

除了url path 改为 /api/course ，请求消息和响应消息 的 格式、意义 和 列出课程API 一致

列出专题

请求

  • 请求头
GET /api/course?action=listbypage&pagenum=1&pagesize=5&keywords=&withoutcontent=true&withuserstate=true&categorytags={"selectedCategoryIds":[52,59],"selectedTagIds":[34,21]}
Cookie: sessionid=<sessionid数值>
  • url参数

请求参数 格式、意义 和 列出课程API 一致

响应

后端返回列出结果，响应格式和 列出课程API 响应格式一致

  • 消息体
{
  "ret":0,
  "items":[
    {
      "id":75,
      "pubdate":"2021-01-18T07:49:46.068Z",
      "author":1,
      "title":"selenium自动化全套课程",
      "status":1,
      "coverimage":"/upload/1_20210118154852_7619.png",
      "thumbupcount":0,
      "favorcount":0,
      "price":"1",
      "purchasecount":1,
      "approved":1,
      "reviewcomments":null,
      "author_name":"白月黑羽",
      "userstate":""
    },
    {
      "id":74,
      "pubdate":"2020-12-21T00:00:00Z",
      "author":32,
      "title":"Python图形界面",
      "status":1,
      "coverimage":"/upload/1_20210118154852_3319.png",
      "thumbupcount":3112,
      "favorcount":489,
      "price":"200",
      "purchasecount":0,
      "approved":1,
      "reviewcomments":"",
      "author_name":"teacher0030",
      "userstate":""
    }
  ],
  "total":65,
  "keywords":""
}

ret 为 0 表示列出成功

total 为 65 表示系统中（不是当前页）总共有65个专题

items 数组 里面包含了当前页中的专题信息。

每个专题信息的 存储格式和含义同上面的列出课程接口