Skip to content

凌晨四点 API v0.1

Jump to bottom
Brian Lee edited this page Feb 16, 2016 · 8 revisions

仿照这篇文档，尝试设计一套能用的 RESTful API.

目录

基本规范说明

  • 浏览器或其他 agent 通过 GET/POST/PUT/DELETE 方法访问对应的 URL 获取/修改数据。
  • 后台返回 JSON 格式的数据，编码为 UTF-8。
  • 如果操作成功，后台将返回 {success: "1", data: <some object>} 格式的数据， data 根据不同的接口有不同的对象。
  • 如果操作失败，返回 {success: "0", msg: "description for the error"}.
  • 接口说明中的 "..." 表示任意的内容（内容与特定的接口相关）。
  • 接口分为以下几个部分：
    • User: 涉及用户的相关操作。如登录，登出等。
    • Courses: 涉及课程的相关操作。如添加课程，删除课程等。
    • Classes: 涉及教学班的相关操作。如添加教学班，为教学班添加学生、指定TA等。
    • Homework: 涉及作业的相关操作。如发布作业、提交作业等。

GET/POST/PUT/DELETE 四个方法对应 CRUD 操作。举例：

  • GET /ajax/courses - 获取课程列表
  • GET /ajax/courses/<课程号> - 获取某一课程的详细信息，<课程号> 为表示该课程的整数。
  • POST /ajax/courses - 新增课程。
  • PUT /ajax/courses/<课程号> - 更新某一课程。
  • DELETE /ajax/courses/<课程号> - 删除某一课程。

当然，这些操作必须在用户登录后，且登录的用户具备相应权限方可成功实施。

User

/ajax/login ✔

  • Usage: 登录
  • Method: POST
  • Param:
    • userid: 用户名（即学号）
    • passwd: 密码
  • Success: {success: "1"}
  • Fail: {success: "0", msg: "description for the error"}

/ajax/logout ✔

  • Usage: 登出
  • Method: POST
  • Param: none
  • Success: {success: "1"}
  • Fail: {success: "0", msg: "description for the error"}

/ajax/user/update ✔

  • Usage: 修改用户资料。（暂时只实现了修改密码）
  • Method: POST
  • Param:
    • old-password: 旧密码
    • password: 新密码
  • Success: {success: "1"}
  • Fail: {success: "0", msg: "description for the error"}

Courses

/ajax/courses ✔

  • Usage: 获取当前用户的所有课程
    • Method: GET
    • Param: none
    • Success: {success: "1", data: [<course object>, ...]}
    • Fail: {success: "0", msg: "description for the error"}

/ajax/courses/<课程号> ✔

  • Usage: 获取当前用户的某个课程的详细信息
    • Method: GET
    • Param: none
    • Success: {success: "1", data: <course object>}
    • Fail: {success: "0", msg: "description for the error"}

Classes

/ajax/classes

  • Method: GET
    • Usage: 获取某用户所加入或所任教的教学班
    • Param: none
    • Success: {success: "1", data: [<class object>, ...]}
    • Fail: {success: "0", msg: "description for the error"}

/ajax/classes/<教学班号>

  • Method: GET
    • Usage: 获取某用户所加入或所任教的某个教学班详细信息
    • Param: none
    • Success: {success: "1", data: <class object>}
    • Fail: {success: "0", msg: "description for the error"}

Homework

/ajax/homework ✔ （勉强实现了发布新作业功能，with tons of bugs）

  • Usage: 发布新作业或修改某个作业 Post
  • Method: POST
  • Param:
    • course_id: 课程号
    • homework_id: 作业号 （optional）
    • homework_title: 作业标题
    • homework_description: 作业描述
    • attach_file：上传附件
    • post_date: 发布时间
    • ddl: 作业 DDL
  • Success: {success: "1", data: <homework_post object>}
  • Fail: {success: "0", msg: "description for the error"}

说明:

  • 如果是发布新作业，homework_id 参数为空，系统自动生成。如果是更新，必须带上此参数。
  • 因为 Azure Dreamspark 订阅的限制暂未实现上传附件功能。
  • post_date 与 ddl 的格式为 Long 型整数，意义是 Epoch 至今流逝的 秒数 （与标准的 UNIX Timestamp 相同）。
  • 若 post_date 为空，则系统自动填上服务器当前时间。只有当 post_date 早于等于服务器当前时间，该作业才会被显示出来。

/ajax/homework/<作业号>

  • Method: DELETE ✔
    • Usage: 删除作业号为 <作业号> 的作业 Post
    • Success: {success: "1"}
    • Fail: {success: "0", msg: "description for the error"}

/ajax/homework/<作业号>/submissions

  • Method: POST
    • Usage: 提交作业
    • Param:
      • homework_id: 作业号
      • student_id: 作者学号
      • submit_date: 提交时间
      • attach_file：上传附件
    • Success: {success: "1", data: "..."}
    • Fail: {success: "0", msg: "description for the error"}

附录

<course object>
{
    'course_id': 46000086, // 课程号
    'course_name': "计算机语言及其处理", // 课程名
    'course_begin': "Feb 26, 2016 3:14:42 PM", // 课程开始日期
    'course_end': "Feb 26, 2016 3:14:42 PM", // 课程结束日期
    'teacher': <teacher object> // 如果登录用户为老师，则该对象为用户自己；如果是学生，则为其所在教学班的老师。（待实现：助教呢？）

}

<class object>
{
    'class_id': 46000086153001, // 教学班号
    'class_name': "星期一 2-3 节", // 教学班名
    'teacher': <teacher object>, // 任教老师
    'students': [<student object>, ] // 学生列表
}

<student object> 
{
    'id': 13354146,
    'name': "My Name",
    'userType': 2
}

<teacher object>
{
    'id': 666666,
    'name': "Teacher Name",
    'userType': 14
}

<homework_post object>
{
    'course_id': 46000086, // 课程号
    'homework_title': "我是标题", // 作业标题
    'homework_description': "没有描述", // 作业描述
    'attach_file': "/download/sldkwr.zip", // 附件地址
    'post_date': "Feb 26, 2016 3:14:42 PM", // 发布时间
    'ddl': "Feb 26, 2016 3:14:42 PM" // 作业DDL
}
Clone this wiki locally