Skip to content

Api 文档

Jump to bottom
陶煜 edited this page Jul 19, 2017 · 22 revisions

Api 说明

新生报到网站中所有api符合以下规律

  • 请求成功, http 状态码一定是在 [200-299] 区间之内
  • 请求失败(异常), http 状态码一定不在 [200-299] 区间之内

请求失败(异常)的响应一般如下

{
    "message": "这里是错误信息",
    "code": 403, // 错误编码
    "status_code": 403 // http状态码
}

常见http状态码

状态码 状态 描述
200 成功 请求成功
204 成功 请求成功,并且没有响应正文
401 失败 code==401.1表示没有登录，code==401.3表示没有权限
404 失败 请求的资源不存在
500 失败 服务器发生错误

新生相关api

  • 搜索新生姓名

GET http://bd.tttwd.cn/api/students/{partOfStudentName}/search

请求参数说明

参数名 参数位置 说明
partOfStudentName 请求的url中 新生的部分姓名，可以是拼音

响应

返回搜索结果（姓名数组）

请求示例

curl http://bd.tttwd.cn/api/students/t/search

响应示例

["陶煜", "陶炜"]

  • 判断新生姓名是否存在

判断给定的新生姓名是否存在

GET http://bd.tttwd.cn/api/students/{studentName}/exist

请求参数说明

参数名 参数位置 说明
studentName 请求的url中 新生的完整姓名

响应

  • 姓名存在 http状态码为204 无响应正文
  • 姓名不存在 http状态码为404 有响应正文

请求示例

curl http://bd.tttwd.cn/api/students/陶煜/exist

响应示例

无响应正文

异常响应示例

// http状态码:404
{
    "message": "该学生不存在！",
    "status_code": 404
}

  • 新生登录

新生使用姓名和身份证号码后四位登录

POST http://bd.tttwd.cn/api/auth/login

请求参数说明

参数名 参数位置 说明
student_name POST参数 新生完整姓名
password POST参数 新生的身份证号码后四位

响应

无响应正文

请求示例

curl -d "student_name=陶煜&password=1111" http://bd.tttwd.cn/api/auth/login

响应示例

无响应正文

异常响应示例

// http状态码:403
{
    "message": "登录失败！请检查身份证号码是否输入正确。",
    "code": 403,
    "status_code": 403
}

// or

// http状态码:401
// 此异常发生是因为该新生没有被后台管理员设置为允许报到，请调用后台的允许报到接口。
{
    "status_code": 401
    "code": 401.3,
    "message": "请先到迎新服务台登记后，再次重试！"
}

  • 新生退出登录

新生退出登录接口,此接口需要新生登录

POST http://bd.tttwd.cn/api/auth/logout

请求参数说明

无请求参数

响应

无响应正文

  • 获取当前登录的新生信息

获取新生的信息 该接口需要新生已经登录

GET http://bd.tttwd.cn/api/me

请求参数说明

参数名 参数位置 是否必须 说明
include GET参数 否 获取额外数据

include值说明。

值 说明
student_profile 获取当前登录新生的详细信息
dormitory 获取当前登录新生所选择的宿舍

获取当前登录新生的详细信息

GET http://bd.tttwd.cn/api/me?include=student_profile

获取当前登录新生所选的宿舍信息

GET http://bd.tttwd.cn/api/me?include=dormitory

获取当前登录新生的详细信息和所选的宿舍信息

GET http://bd.tttwd.cn/api/me?include=student_profile,dormitory

响应

返回当前登录的用户信息

请求示例

curl http://bd.tttwd.cn/api/me?include=student_profile,dormitory

响应示例

{
    "data": {
        "id": 10000,
        "student_num": "1508220227",
        "student_name": "陶煜",
        "gender": false, // true为女 false为男
        "gender_str": "男", 
        "id_card_with_mosaic": "342625********1111", // 身份证号码
        "department_class_id": 4,
        "department_class": "计算机学院17级网工(3)班",
        "report_at": "2017-07-16 08:47:06", // 报到时间。 如果该新生没有报到，此值为null
        "arrive_dorm_at": null, // 新生到达宿舍时间。如果该新生没有到达宿舍，此值为null
        "allow_report_at": "2017-07-16 08:47:05", // 后台管理允许报到时间。 如果不允许报到，此值为null
        "created_at": "2017-07-16 08:07:13",
        "updated_at": "2017-07-16 08:47:06",
        "student_profile": {
            "data": {
                "student_id": 10000,
                "graduate_school": "abc中学", // 毕业中学
                "come_from": "安徽省马鞍山市含山县", // 家乡
                "tel": "13911111111", // 手机号码
                "height": null,
                "weight": null,
                "remarks": null
            }
        },
        "dormitory": {
            "data": {
                "id": 1,
                "dorm_num": "9A103",
                "dorm_floor": "1", // 宿舍楼层
                "dorm_ridgepole": "A", // 栋 (A栋|B栋)
                "dorm_unit": "9", // 宿舍单元
                "galleryful": 6, // 宿舍总容纳人数
                "galleryful_in_this_class": 6, // 当前新生所在班级可入住人数
                "already_selected_num_in_this_class": 1, // 已住人数
                "insert_dormitory_num": 0, // 此字段大于0表示该宿舍是插宿
                "is_together_dormitory": false, // 是否为合宿
                "gender": false, // true为女生宿舍 false为男生宿舍
                "created_at": "2017-07-16 08:07:13",
                "updated_at": "2017-07-16 08:07:13"
            }
        }

    }
}

异常响应示例

见一般异常响应

  • 获取当前登录的新生可以入住的宿舍

根据当前登录的新生所在班级和性别获取宿舍

GET http://bd.tttwd.cn/api/dormitories/available

请求参数说明

无请求参数

响应示例

{
    "data": [
        {
            "id": 1,
            "dorm_num": "9A103",
            "dorm_floor": "1", // 宿舍楼层
            "dorm_ridgepole": "A", // 栋 (A栋|B栋)
            "dorm_unit": "9", // 宿舍单元
            "galleryful": 6, // 宿舍总容纳人数
            "galleryful_in_this_class": 6, // 当前新生所在班级可入住人数
            "already_selected_num_in_this_class": 1, // 已住人数
            "insert_dormitory_num": 0, // 此字段大于0表示该宿舍是插宿
            "is_together_dormitory": false, // 是否为合宿
            "gender": false, // true为女生宿舍 false为男生宿舍
            "created_at": "2017-07-16 08:07:13",
            "updated_at": "2017-07-16 08:07:13"
        },
        // ...
    ]
}

异常响应示例

见一般异常响应

  • 新生确认报到

新生确认报到接口 POST http://bd.tttwd.cn/api/set_report

请求参数说明

无请求参数

响应

无响应正文

异常响应示例

见一般异常响应

  • 新生选择宿舍

新生选择宿舍接口 POST http://bd.tttwd.cn/api/select_dorm/{dormitory_id}

请求参数说明

参数名 参数位置 说明
dormitory_id 请求的url中 所选的宿舍id

响应

无响应正文

异常响应示例

见一般异常响应

  • 新生取消选择宿舍

新生取消选择宿舍接口 POST http://bd.tttwd.cn/api/cancel_dorm

请求参数说明

无请求参数

响应

无响应正文

异常响应示例

见一般异常响应

  • 获取宿舍学生

获取新生的信息 该接口需要新生已经登录

GET http://bd.tttwd.cn/api/dormitories/{dormitory_id}/students

参数说明

参数名 参数位置 说明
dormitory_id 请求的url中 宿舍id

响应示例

{
    "data": [
        {
            "id": 10000,
            "student_num": "1508220227",
            "student_name": "陶煜",
            "gender": false,
            "gender_str": "男",
            "id_card_with_mosaic": "342625********1111",
            "department_class_id": 4,
            "department_class": "计算机学院17级网工(3)班",
            "report_at": "2017-07-19 11:54:45",
            "arrive_dorm_at": null,
            "allow_report_at": "2017-07-19 11:54:31",
            "created_at": "2017-07-19 08:09:39",
            "updated_at": "2017-07-19 11:54:45"
        },
        {
            "id": 10001,
            "student_num": "1508220228",
            "student_name": "陶炜",
            "gender": false,
            "gender_str": "男",
            "id_card_with_mosaic": "342625********1111",
            "department_class_id": 4,
            "department_class": "计算机学院17级网工(3)班",
            "report_at": "2017-07-19 11:56:45",
            "arrive_dorm_at": null,
            "allow_report_at": "2017-07-19 11:54:34",
            "created_at": "2017-07-19 08:09:39",
            "updated_at": "2017-07-19 11:56:45"
        }
    ],
    "meta": {
        "dorm_num": "9A103" ／/ 当前宿舍号
    }
}

管理员相关api

  • 管理员登录

管理员登录

POST http://bd.tttwd.cn/api/admin/login

请求参数说明

参数名 参数位置 说明
name POST参数 管理员用户名
password POST参数 管理员密码

响应

无响应正文

  • 管理员退出登录

管理员退出登录,此接口需要管理员登录

POST http://bd.tttwd.cn/api/admin/logout

请求参数说明

无请求参数

响应

无响应正文

Clone this wiki locally